Using the Authorization Code Grant

The authorization code grant provides security and the ability to refresh expired tokens. Use the authorization code grant for user applications when your application has a server component that can protect its secret key.

This grant is not suitable for service integrations.

On this page

The Authorization Code Grant uses the DocuSign Authentication Service instead of the usual REST API endpoints. See Working With the Authentication Service to learn more.

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

  • account-d.docusign.com for the developer sandbox
  • account.docusign.com for the production platform

Starting the Authentication Code Grant

To begin the Authentication Code Grant, you would direct the user to https://account-d.docusign.com/oauth/auth . with the following query parameters: For this grant, the response_type must be code.

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

The user is asked to log in to their DocuSign account (if not already logged in), and then sees a consent dialog:

See Sending the Initial Authentication Request for details about the query parameters to this request.

Although the state parameter is optional, we strongly recommend that you use it to avoid cross-site request forgery attacks. See Using the State Parameter to learn more.

Handling the Response

If the authentication is successful, the authentication service redirects the user to the redirect_uri. The callback contains a code that you will exchange for a token in the next step.

HTTP/1.1 302 Found
Location: https://client.example.com/callback?
  code=eyJ0eX...ei0iLIFk3A
  &state=a39fh23hnf23

The code parameter is always present. The state parameter is present only if you provided it in the initial request.

Callback Query Parameter Description
code An authorization code you can use to request an access token and refresh token.
state The value of the state passed into the original request. If a value is provided, clients must validate it is exactly equal to the value provided in the request.

Exchanging the Code for a Token

Once you have an authorization code, use the /oauth/token endpoint to obtain access and refresh tokens. You will use the access token to make API calls.

Make a POST request to /oauth/token with the following headers and parameters. The Authorization header contains the word Basic and the base64 representation of your integrator key and the secret key you generated when you set up the integration in DocuSign Admin. The two keys are concatenated with a colon :.

For example, if your integrator key is 230546a7-9c55-40ad-8fbf-af205d5494ad and the secret key is 3087555e-0a1c-4aa8-b326-682c7bf276e9 you can get the base64 value like this in a JavaScript console:

btoa('230546a7-9c55-40ad-8fbf-af205d5494ad:3087555e-0a1c-4aa8-b326-682c7bf276e9')
"MjMwNTQ2YTctOWM1NS00MGFkLThmYmYtYWYyMDVkNTQ5NGFkOjMwODc1NTVlLTBhMWMtNGFhOC1iMzI2LTY4MmM3YmYyNzZlOQ=="

The body of the POST request needs two parameters:

Body Parameters Description
grant_type Must be authorization_code to exchange an authorization code for an access token.
code The authorization code that you received from the callback.

With the Authorization header and the body parameters, the POST request would look like this. Note that the Content-Type: application/x-www-form-urlencoded header is also required.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MjMwNTQ2YTctOWM1NS00MGFkLThmYmYtYWYyMDVkNTQ5NGFkOjMwODc1NTVlLTBhMWMtNGFhOC1iMzI2LTY4MmM3YmYyNzZlOQ==

grant_type=authorization_code&code=eyJ0eX...ei0iLIFk3A

If the request is succesful, the authentication service issues an access token and a refresh token as a JSON object.

{
  "access_token": "eyJ0eX...ZgbI2xzCoA",
  "token_type": "Bearer",
  "refresh_token": "eyJ0eX...XD8IDlL6GA",
  "expires_in": 28800
}

The fields of the JSON response are:

Body Parameters Description
access_token The token you will use in the Authorization header of calls to the DocuSign API.
token_type This is the kind of token. It is usually Bearer
refresh_token A token you can use to get a new access_token without requiring user interaction.
expires_in The number of seconds before the access_token expires.

Once you have the access_token, use it in in the Authorization header whenever you call an API endpoint. Note that you must include the token type in the header.

Authorization: Bearer eyJ0eX...ZgbI2xzCoA

Getting the User’s Account and Base URI Information

The first thing you should do after getting your access token is to use the /oauth/userinfo endpoint to get user’s account and base URL information that you’ll use to access the DocuSign API.

Using Refresh Tokens

You can use a refresh token to get new access token after the access token expires. Refresh tokens usually do not require the account user to log in again.

Refresh tokens typically have a longer lifetime than access tokens, but they do expire. To request a refresh token with the longest possible lifetime (depending on account and system security policies) use extended scope when you make the initial authentication request.

To get a new access token, use the refresh token as you would an authorization code, but with different body parameters to the POST request:

Body Parameters Description
grant_type Must be refresh_token to exchange refresh token for an access token.
refresh_token The refresh token you got with the access token.

The Content-Type and Authorization headers for the refresh request are the same as the ones you used to exchange the authorization code for the access token.

POST /oauth/token
Host: account.docusign.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic MjMwNTQ2YTctOWM1NS00MGFkLThmYmYtYWYyMDVkNTQ5NGFkOjMwODc1NTVlLTBhMWMtNGFhOC1iMzI2LTY4MmM3YmYyNzZlOQ==

grant_type=refresh_token&refresh_token=ey4fdd3nd.AAAA3d2ddagq3.akd1243d31d

Instead of waiting for an access token to expire, we recommend that you refresh the access token when its expiration time is within 30 minutes, for example. When you first get the access token, use the expires_in value to calculate an expiration time. Store this expiration time in the user’s session.

Before making a call to the DocuSign API, check the current time against the expiration time. If it is within the threshold, use the refresh token to get a new access token. If the response to the refresh operation is an error, or if the new access token’s expires_in value is less than your threshold, you will need to repeat the initial authentication flow. An already logged in user may not need to reauthenticate with a password.