How to get an access token with Implicit Grant | Docusign

This topic demonstrates how to generate an access token manually using Implicit Grant authentication. In the Implicit Grant flow, your integration requests an access token directly.

Prerequisites

To obtain an access token with Implicit 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.
Your application is set to use Implicit Grant authentication.	To set your application to use Implicit Grant authentication: Open the Apps and Keys page for your developer account. Under Apps and Integration Keys, choose the Integration Key to use, then select Actions, then Edit. In the Authentication section, select Implicit Grant.

Step 1. Obtain the access token

To begin the Implicit Grant flow, your application redirects the user’s browser to a constructed authorization URI where they will grant consent and obtain an access token directly.

To get this consent, open the accompanying Sample URI in your embedded browser, replacing the value of client_id with your integration key.

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

After selecting 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 a display error message, which you can safely ignore. The access_token query parameter in the page URI contains the value of the access token that you can use to make API calls. Save it in preparation for the next step.

See details: Authorization code request syntax

The constructed URI for obtaining consent contains five 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
Your application’s integration key.
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 token.

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 access token.

See How to obtain individual consent for details.

https://account-d.docusign.com/oauth/auth?
    response_type=token
    &scope=YOUR_REQUESTED_SCOPES
    &client_id=YOUR_INTEGRATION_KEY
    &redirect_uri=YOUR_REDIRECT_URI

Step 2. 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 3. 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"

Troubleshoot errors

BadRequest

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

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

Consent_Required

Indicates that the user has not consented to allow your application to make calls on their behalf or you have not requested a scope that is required for the operation.

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

Invalid authentication request: The response type is not supported

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

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.

Page cannot be displayed after requesting the code

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

Next steps

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