Working With the Authentication Service

The DocuSign authentication service hosts all of the necessary OAuth2 endpoints for the Authorization Code Grant and the Implicit Grant.

The authentication service uses different host names for the production environment and the developer sandbox.

Hostname Environment
https://account-d.docusign.com Developer sandbox, also called Demo
https://account.docusign.com Production

To communicate with the authentication service, you send HTTP requests to these endpoints.

Endpoint Description
/oauth/auth Use the auth endpoint to initiate the authorization process.
/oauth/token If you are using the authorization code grant, you’ll use the token endpoint to exchange a code for a token. This end point is also used to refresh a token.
/oauth/userinfo Once you have a token, use the userinfo endpoint to get the user’s account and base url informatioin. You’ll use these for subsequent API requests.

Sending the Initial Authentication Request

The first step for the both the authorization code grant and implicit grant flows is to redirect the user to the authentication service. Whether the user clicks a link or is redirected by your service, this will result in the browser making a GET request to the /oauth/auth endpoint, which requires several parameters in the query string.

Query Parameter Required Description
response_type Yes Use code for authorization code grant.
Use token for implicit grant.
client_id Yes Use the integrator key that you generated.
redirect_uri Yes The redirect URI must exactly match one of those pre-registered for the integrator key. This determines where to redirect the user after they successfully authenticate.
scope Yes signature is currently the only supported value. It allows you to create and send envelopes and to obtain links for starting signing sessions.
state No Allows for arbitrary state that may be useful to your application. The value in this parameter it is returned with the redirect response. See Using the State Parameter.
ui_locales No List of the end-user’s preferred languages, represented as a space-separated list of RFC5646 language tag values ordered by preference.
For example, fr-CA fr en.

This is what the initial authentication request looks like when you use the Authorization Code Grant.

GET /oauth/auth?
  response_type=token
  &scope=signature
  &client_id=230546a7-9c55-40ad-8fbf-af205d5494ad
  &state=a39fh23hnf23
  &redirect_uri=http://www.example.com/callback

As part of this request, the authentication service displays a login page in the user’s browser. After the user logs in to DocuSign and approves or rejects the integration, the authentication service redirects the user to the redirect_uri that you specified in the initial request. This URI must exactly match the URI you specified when you set up the integration in DocuSign Admin.

If the redirect_uri is http://www.example.com/callback, your code running at http://www.example.com/callback should handle the response.

If authentication does not complete successfully, the user might be redirected to the redirect_uri with an error response like this:

HTTP/1.1 302 Found
Location: https://client.example.com/callback?
  error=invalid_request
  &error_description=Unsupported%20request.
  &state=a39fh23hnf23

Only the error parameter is required. The callback may contain additional query parameters that you can use to let the customer know more about the error.

Query Parameter Description
error A well-known error string indicating the cause of the failure.
error_description A string that can be presented directly to the end-user. This parameter is optional.
state If you provided a state parameter in the initial request, it will appear here.

Using the State Parameter

Although the state parameter is optional, we strongly recommend that you use it to avoid cross-site request forgery attacks. You should set the state parameter to an unguessable string known only to your application, and check to make sure that the value has not changed between requests and responses.

See the following sections in the OAuth2 RFCs to learn more.