Working With the Authentication Service

The DocuSign authentication service hosts all of the necessary endpoints for the OAuth authentication methods:

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

Hostname Environment Developer sandbox, also called Demo 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 Space-separated list of one or more scopes. See the scope table below. Encode the space character as %20 in URLs.
prompt No If set to login then the authentication server will prompt the user for re-authentication, even if they have an active login session.
If the parameter is omitted, then the user may not be prompted (silent authentication) if they have an active login session.
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. Encode the space character as %20 in URLs.
For example, fr-CA%20fr%20en.

The scope query parameter is a space-separated list of the following values:

Scope Permissions granted
signature Create and send envelopes, and obtain links for starting signing sessions.
extended Obtain a refresh token with an extended lifetime.
impersonation Obtain access to the user’s account when the user is not present. This scope is used by Service Integration Authentication.

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

GET /oauth/auth?

As part of this request, the authentication service displays a login page in the user’s browser. After the user logs in to DocuSign, they are given the opportunity to accept or reject the integration.

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, your code running at 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

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.