How to get an access token using Public Authorization Code Grant | Docusign

This topic demonstrates how to generate an access token manually using Public Authorization Code Grant (ACG). This grant uses Proof Key for Code Exchange (PKCE) to authenticate securely without requiring a client secret.

Walkthrough video

You can also see a walkthrough video of how to get an access token using Public Authorization Code Grant.

Prerequisites

To obtain an access token with Public Authorization Code Grant, you must meet the following prerequisites:

Data element	Description
You have defined an integration key.	An integration key identifies your integration and links to its configuration values. Create an integration key.
You have defined a redirect URI for your integration key.	The redirect URI is the URI (URL) to which Docusign will redirect the browser after authentication. Set a redirect URI.
You have chosen to use Public ACG in your app’s authentication settings.	To select the Public ACG flow, in the User Application section of your apps configuration page in Apps and Keys, for the question Is your application able to securely store a client secret, select No. For the Select App Type section, choose Single Page Web Application if you are using CORS, or Native OS Application if you are not. Using a single-page web app with CORS will also require that you add an Origin URL and select the Allow CORS for OAuth calls checkbox. See Single-page applications and CORS for details. This example how-to shows the basic Public ACG flow and does not include CORS.

Step 1. Create code challenge

Public Authorization Code Grant uses a code challenge to validate the identity of your app. Before you make any API calls, you should create the values for this code challenge to be used in later steps.

Generate a cryptographically random string to use as the code_verifier.
Hash the string you generated with the S256 algorithm, then base-64URL encode it. The resulting value is the code_challenge.

Note: As a best practice for generating cryptographically random strings:

For C#, use System.Security.Cryptography.RNGCryptoServiceProvider.
For Java, use java.security.SecureRandom.
For Node.js, use the built-in crypto package randomBytes; it has synchronous and asynchronous forms.

R8zFoqs0yey29G71QITZs3dK1YsdIvFNBfO4D1bukBw

Step 2. Request the authorization code

Before you can make any API calls using Public Authorization Code Grant, you must get your user’s consent for your app to act for them and obtain an authorization code.

To get this consent, open the accompanying example URI in your embedded browser, replacing the value of client_id with your integration key and replacing the code_challenge value with your code challenge.

Your user will be prompted to sign in to their account and give consent for your app to make calls on their behalf.

Once the user selects Accept, if you used localhost as your redirect URI, your browser may attempt to load the query parameters as a web page. This will result in displaying an error message, which you can safely ignore. Select the value of the code query parameter in the page URI, then save it to use in the next step.

See details: Authorization code request syntax

The constructed URI for obtaining consent and getting an authorization code contains several parts:

A base path for the authentication service. This path differs depending on whether your app is in the developer environment or in production.
- For the developer environment, the base URI is https://account-d.docusign.com/oauth/auth
- For the production environment, the base URI is https://account.docusign.com/oauth/auth
A Base64URL-encoded redirect URI that matches one of those configured for the application with the specified integration key.
A space-delimited list of the scopes your app needs. For this example, use the signature scope, which enables your app to call the eSignature REST API.
A response_type value of code, indicating that your app is using Authorization Code Grant.
An optional state value that you can use to prevent CSRF and replay attacks. See Prevent attacks and redirect users with OAuth 2.0 State Parameters and OAuth replay attack mitigation for details.
An optional login_hint that enables you to prepopulate the email address field on the sign-in screen.
A code_challenge_method field indicating the type of encryption that was used to create the code challenge. The only supported value is S256.
The code_challenge from the previous step.

The accompanying URI syntax and Sample URI show how these values map to the sections of the URI.

After your user logs in and grants permission, your app will be able to make API calls on their behalf. A set of query parameters will be returned to the redirect URI; for the Authorization Code Grant flows, the code query parameter will be used in the next step.

Note: Redirect URIs cannot contain fragment components. If your app needs to use a fragment, record that fragment in the state parameter (which will be returned along with the redirect URI) and re-combine the fragment and the redirect URI in your app after the initial call to get the authorization code.

See How to obtain individual consent for details.

https://account-d.docusign.com/oauth/auth?
   response_type=code
   &scope=YOUR_REQUESTED_SCOPES
   &client_id=YOUR_INTEGRATION_KEY
   &state=YOUR_CUSTOM_STATE
   &redirect_uri=YOUR_REDIRECT_URI
   &code_challenge_method=S256
   &code_challenge=YOUR_CODE_CHALLENGE

Step 3. Obtain the access token

To request an access token, send a POST request containing your authorization code to the Docusign authentication service.

For the developer environment, the token URI is: ‘https://account-d.docusign.com/oauth/token’
For the production platform, the token URI is: ‘https://account.docusign.com/oauth/token’

To validate your identity, you must also supply the code_verifier values along with this request. Docusign will hash and Base64URL-encode the provided code_verifier and compare the result to the code_challenge from the initial authorization request. If the values are equal, your access token will be returned in the response.

CORS: If you are using a single-page app with CORS, you must also include an origin header that contains the value of one of the origin URLs that you defined in your app’s CORS configuration. This example how-to shows the basic Public ACG flow and does not include CORS. See Single-page applications and CORS for details.

Note: The authorization code is only viable for two minutes. If more than two minutes pass between obtaining the authorization code and attempting to exchange it for an access token, the operation will fail.

See details: Request elements

The access token request contains the following set of body parameters.

Parameter	Description
`grant_type`	The type of grant being used. To exchange an authorization code for an access token, use `authorization_code`.
`code`	The authorization code that you received from the callback.
`client_id`	Your app’s integration key.
`code_verifier`	The code verifier value that you created in step 1.

The access token contains the following fields.

Name	Description
`access_token`	The value of the access token. This value will be added to the `Authorization` header of all Docusign API calls.
`token_type`	The type of token. For access tokens, the value of this will be `Bearer`.
`refresh_token`	A token that you can use to obtain a new access token without requiring user consent. The lifetime of a refresh token (typically around 30 days) can vary depending on business needs and is subject to change at any time. When you use a refresh token to authenticate, you can obtain a new refresh token with the following behavior: If you have obtained the `extended` scope, a new refresh token is issued with a full lifetime (typically 30 days). If you do not have `extended` scope, a new refresh token is issued that has the same expiration date as the original token (typically 30 days from first login).
`expires_in`	The number of seconds before the access token expires.
`scope`	The scopes granted by the access token.

curl
--data "grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&code_verifier=YOUR_CODE_VERIFIER&client_id=YOUR_INTEGRATION_KEY"
--request POST https://account-d.docusign.com/oauth/token

Step 4. Get your user’s base URI

To make an API call to the Docusign platform, your application needs both an access token (which you obtained in the previous step), and a base URI that is unique to the user on whose behalf your application is making the API call.

To get the base URI, call the /oauth/userinfo endpoint, supplying your application’s access token as a header.

For the developer environment, the URI is https://account-d.docusign.com/oauth/userinfo
For the production environment, the URI is https://account.docusign.com/oauth/userinfo

The request must contain an Authorization header that holds your access token.

Name	Description
Authorization	Contains the word `Bearer` and the access token that you received in the previous step.

If successful, this returns a set of data for each user who has granted consent and the account(s) that user is a member of, as shown by the Sample response.

You will need the account_id and the base_uri claims of the user that your application is acting on behalf of to make calls to a Docusign API.

Docusign enforces hourly limits on the number of /oauth/userinfo requests per user ID and per integration key. See User info endpoint limits for details.

GET https://account-d.docusign.com/oauth/userinfo
Authorization: Bearer YOUR_ACCESS_TOKEN

Step 5. Use the access token to make an API call

Now that you’ve obtained an access token and the user info, your application is authenticated and has all of the information that it needs to make a call to a Docusign API. To make an eSignature REST API request, you must include:

The acquired access token in the request’s Authorization header.
The base URI for the request, built from the account_id and the base_uri of the user account.

For example, the syntax to call AccountBrands:list to return details about all of the brands associated with an account is: GET restapi/v2.1/accounts/{accountId}/brands

Substituting the base URI of https://demo.docusign.net and API Account ID of 18b4799a-xxxx-xxxx-xxxx-b5b4b8a97604, the request path would be: GET https://demo.docusign.net/restapi/v2.1/accounts/18b4799a-xxxx-xxxx-xxxx-b5b4b8a97604/brands

The final piece of information needed to access the API is the access token, prefixed with Bearer and provided in the Authorization header.

Sample request

curl -- request GET https://demo.docusign.net/restapi/v2.1/accounts/18b4799a-xxxx-xxxx-xxxx-b5b4b8a97604/brands
--header "Authorization: Bearer eyJ0eX...V8KroQ"

Use refresh tokens

You can use a refresh token to get a new access token after the access token expires. Depending on account and system security policies, refresh tokens may have a longer lifetime than access tokens. Refresh tokens usually do not require the account user to log in again.

To get a new access token, use the refresh token as you would an authorization code, but with a grant_type value of refresh_token and a refresh_token parameter that holds the contents of the refresh token.

The following table describes the elements of the request syntax.

Name	Description
`grant_type`	The type of grant being used. To exchange a refresh token for an access token, use `refresh_token`.
`refresh_token`	The full refresh token value that you originally received from authentication.

Refresh tokens may be used for a variable period of time (that partially depends on business needs and may change at any time, but typically about 30 days) after the first authentication. When your application uses the refresh token to authenticate, it will be issued a new refresh token.

If you have obtained the extended scope, a new refresh token is issued with a full lifetime (typically 30 days). It is possible for a user to remain logged in indefinitely by requesting the extended scope and continually refreshing its access token.
If you do not have the extended scope, a new refresh token is issued that has the same expiration date as the original token (typically 30 days from first login).
If you receive any errors during the refresh operation, your integration should prompt the user to log in again to obtain a new access and refresh token.
If your app is configured as a Single Page App (SPA) in its Authentication settings, a new refresh token is issued with a shorter lifetime of 24 hours. Refresh tokens for SPA apps cannot be extended, even if you request the extended scope.

Instead of waiting for an access token to expire, Docusign recommends that you refresh the access token when it is close to expiring (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.

POST https://account-d.docusign.com/oauth/token grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_INTEGRATION_KEY

Troubleshoot errors

refresh_token_mismatch

Indicates that the user’s password has changed and their refresh token has been revoked as a consequence. In this case, go through the flow again to get a new access token.

expired_client_token

Indicates that the refresh token has expired. In this case, go through the flow again to get a new access token.

user_does_not_belong_to_specified_account

Typically indicates that there is a mismatch between the authenticated user and the account ID provided in an API call, but can also be generated when the integration targets the wrong server for the user’s account.

Invalid request

Getting an “Invalid request” error without additional info during the step to exchange your authorization code for an access token can indicate that the code verifier and code challenge you provided don’t match. Make sure that your code challenge is S256-encrypted and Base64URL-encoded.

Invalid grant

Indicates one or more of the following problems:

The supplied authorization code is incomplete or expired. Make sure that there are no extra spaces on the start and end portions of the string, and that no characters have been truncated. If you used the state parameter, make sure that you’ve removed it from the end of the returned code value.

If you encounter this error repeatedly and/or after verifying that all parameters are correct, ask the user to log in again.
The code challenge and the code verifier may not be valid. Ensure that you have correctly hashed and Base64URL-encoded the verifier to get the challenge.

Invalid grant: Origin required but not included

If you are using a single-page app with CORS, you must also include an origin header that contains the value of one of the origin URLs that you defined in your app’s CORS configuration. This example how-to shows the basic ACG with PKCE flow and does not include CORS. See Single-page applications and CORS for details.

Invalid authentication request: The response type is not supported

Indicates that the application attempting to use Authorization Code Grant authentication is configured to use Implicit Grant authentication. It must be set to use Authorization Code Grant.

To change the Authentication setting:

Open the Apps and Keys page.
Under My Apps / Integration Keys, choose the integration key to use, then select Actions, and then Edit.
Select Authorization Code Grant with Proof Key for Code Exchange.

Token type mismatch

Indicates that your app has supplied the wrong type of token for a step in the authorization flow. For example, attempting to use a refresh token as an access token will result in this error. Make sure that your app is supplying the correct type of token for its step in the authorization flow.

Client ID is disabled

Indicates that your app has been set as disabled. Enable your app, then try again.

Invalid user site ID

Indicates that the app called a site other than the user’s home site. Make sure that you are using the same site and domain to provide the token as those that you originally acquired it from.

Issuer not found

Indicates that the user is not present in the domain or environment (developer or production) used for the authentication flow. Make sure that you have specified the right domain and environment.

User not found

Indicates that the specified user does not exist. Make sure that the user is a member of your app’s organization.

Bad Request

Make sure that your application is attempting to connect to the correct authentication URI.

For the developer environment, you should use URIs from the https://account-d.docusign.com/oauth domain.
For the production platform, you should use URIs from the https://account.docusign.com/oauth domain.

Invalid authentication request: The response type is not supported.

Indicates that the response type specified in the authorization code request is not set to code. Ensure that the value of the response_type header is code.

Invalid RedirectUri

Indicates that the redirect URI specified for authentication does not match any of the redirect URIs defined for the integration key. The redirect URI strings must match exactly, including space and slash characters.

Consent_required

Indicates that the user has not consented to allow your application to make calls on their behalf. Also can be generated when

You have not requested a scope that is required for the operation.
You are attempting to grant admin consent but have not claimed a domain for your organization, or because you are missing a required organization entitlement. If you suspect this might be the cause of your error, please open a support case.
You attempt to grant consent as the wrong user. To ensure that you are logging in as the correct user, add &prompt=login to your consent URI.

If the user has supplied consent and is still receiving this error, there may have been something wrong with the URI being used. Double-check to make sure the integration key has not been cut off and that you have all required scopes.

Page cannot be displayed after requesting the code

Indicates that the redirect URI is not set to a valid web page.

Next steps

See Public Authorization Code Grant for context about this authentication flow.
See Choose an OAuth type for a breakdown of the advantages and disadvantages of each OAuth option, including Public Authorization Code Grant.