Using the Implicit Grant

The implicit grant flow should be used only by user applications that do not have the ability to protect a secret key on a remote server. This grant is not suitable for service integrations.

If you use the implicit grant, you must select the This is a mobile app option when you generate your integrator key in DocuSign Admin.

On this page

The implicit grant flow uses the 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 Implicit Grant

To begin the Implicit 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 token.

https://account-d.docusign.com/oauth/auth?
   response_type=token
  &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.

Processing the Response

If the authorization succeeds, the authentication services redirects the user to the redirect_uri and provides the token in a hash fragment.

HTTP/1.1 302 Found
Location: https://client.example.com/callback\#
  access_token=eyA3J3ad.k32jdskd.ann4ds
  &token_type=bearer
  &expires_in=3600
  &state=a39fh23hnf23
Hash Fragment 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
expires_in The number of seconds before the access_token expires.
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.

Note that the hash fragment (everything after the # in the redirection request) is not sent to the server that hosts your web page. This means that your code running at http://www.example.com/callback in this example, must parse the fragment using something like location.hash in JavaScript.

The length of OAuth access codes and tokens is variable. It is normal for the token to be 550 characters or longer. Do not make assumptions about its length.

Clients that implement this flow should provide an opportunity to cancel in case the request fails, and it is not possible to redirect the user to the redirect_uri.

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 eyA3J3ad.k32jdskd.ann4ds

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.