Skip to navigation
Platform 101AuthenticateAuthentication reference

Obtain consent endpoint

View as Markdown

You can redirect a user’s browser window to the GET /oauth/auth endpoint to obtain consent. This is the first step in several authentication scenarios. It has different functions when supplied with different parameters.

When you navigate to it in a browser, you can use this endpoint to:

  • Obtain individual or admin consent in any of the authentication scenarios.
  • Obtain an authorization code for the Authorization Code Grant flow.
  • Obtain an access token directly, using the Implicit Grant flow.

The syntax and parameters used for calling this endpoint in your browser are shown below.

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

The authorization request includes several parameters used in conjunction with the base URL that configure specific authentication options:

ParameterRequired?Description
response_typeYesThe type of grant to be used.

For the Authorization Code Grant, this value should be code.
scopeYesA space-separated list of the scope permissions being requested for the client. When working with the eSignature API, this value should be signature. This allows your application to create and send envelopes, and obtain links for starting signing sessions.

When using JWT authentication, this should also include impersonation.
client_idYesYour application’s integration key.
promptNoDetermines whether the authentication server will prompt the user for reauthentication.

If set to login, then the authentication server will prompt the user for reauthentication, even if they have an active login session. If the parameter is omitted, then the user will not be prompted to reauthenticate (silent authentication) if they have an active login session.
stateNoHolds a special implementation-specific value that is returned with the authorization code.

Although the state parameter is optional, we strongly recommend that you use it to avoid cross-site request forgery attacks. You should set the state parameter to a secure string known only to your application, and check to make sure that the value has not changed between requests and responses.

See the following sections in the OAuth2 RFCs to learn more:

Cross-Site Request Forgery in The OAuth 2.0 Authorization Framework

state Parameter in OAuth 2.0 Threat Model and Security Considerations
redirect_uriYesThe URI to which Docusign will redirect the browser after authorization has been granted by the user.

The redirect URI must exactly match one of those preregistered for the integration key in your Docusign account. This determines where to redirect the user after they successfully provide consent.

After a successful call, the Authentication Service verifies that the client application is valid and has access to the requested scope. If so, it returns the requested data to the provided redirect URI as a query parameter:

  • In the Implicit Grant scenario, it returns access token and metadata.
  • In the Authorization Code Grant scenario, it returns the authentication code and state, if any.

Next steps