Skip to navigation
Platform 101AuthenticateAuthentication reference

Obtain access token endpoint

View as Markdown

The POST /oauth/token endpoint returns tokens based on your supplied parameters.

You can use this endpoint to:

The syntax and parameters used for making a call to this endpoint differ, depending on your use case. See JWT Grant and Confidential Auth Code Grant for details and example API calls.

If you are exchanging an authorization code for an access token using the Authorization Code Grant flow, you must include the following call headers:

NameDescription
Content-TypeA standard HTTP entity header indicating the media type of the resource. The value of Content-Type must be application/x-www-form-urlencoded.
AuthorizationThe Authorization header contains your integration key and secret key, concatenated by a colon character, converted into Base64 and prefixed with the word Basic. This value, together with the authorization code, is required to obtain an access token.

For example, if your integration key is 7c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f and the secret key is d7014634-xxxx-xxxx-xxxx-6842b7aa8861, you can get the Base64 value in a JavaScript console with the following method call:
btoa('7c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f:d7014634-xxxx-xxxx-xxxx-6842b7aa8861')
This method call results in a new Authorization header value:
NWMyYjhkN2.....hODg2MQ==
refresh_tokenThe full refresh token value that you originally received from authentication. This is only used if you are exchanging a refresh token for a new access token.

Calls to this endpoint have the following set of body parameters:

NameRequired?Description
grant_typeYesThe type of grant being used:

To exchange an authorization code for an access token, use authorization_code.

To exchange a JWT for an access token, use urn:ietf:params:oauth:grant-type:jwt-bearer.
assertionOnly used if you are exchanging an JWT for an access token.The encoded value of a JWT token containing your authentication data.
codeOnly used if you are exchanging an authorization code for an access token.The authorization code that you received from the callback.

After a successful call, the authentication service verifies that provided data is valid and returns the requested access token and metadata.

The response contains the following fields:

NameTypeDescription
access_tokenstringThe value of the access token. This value will be added to the Authorization header of all Docusign API calls.
token_typestringThe type of token. For access tokens, the value of this will be Bearer.
refresh_tokenstringA 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 the first login).

Note: A refresh token is only returned in the Authorization Code Grant flow.
expires_inintThe number of seconds before the access token expires. When your access token expires, your application should request a new access token or, if you are using one of the Authorization Code Grants, get a new access token using your refresh token.
scopestringEach Docusign API defines a set of scopes. Each scope is required to perform a set of actions associated with that API. See Authentication scopes for the full list of available scopes and the APIs they are associated with.

Next steps