Skip to navigation

How to obtain individual consent

View as Markdown

The most straightforward way to obtain consent for your application to act on a user’s behalf is to directly ask that user, getting their individual consent.

When an application authenticates to perform actions on behalf of a user, that user will be asked to grant consent for the set of scopes (sets of permissions) that the application has requested, unless they have previously granted that consent.

Video walkthrough

You can also see a video walkthrough of how to obtain individual consent, shown below:

Prerequisites

To grant individual consent, you must meet the following prerequisites:

Data elementDescription
You have defined an integration key.An integration key identifies your integration and links to its configuration values. To create an integration key:
1. Open the Apps and Keys Page.
2. Under My Apps / Integration Keys, select Add App / Integration Key, then give it a name.
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. To define a redirect URI:
1. Open the Apps and Keys page.
2. Under My Apps / Integration Keys, choose the integration key to use, then select Actions, then Edit. In the Additional Settings section, select Add URI.
3. Enter the new redirect URI. This can be a localhost address.

Step 1. Open the Docusign authorization URI

To begin authentication and obtain consent, your app will open a constructed Docusign authorization URI. Note that this is not a standard GET request and cannot be directly sent by the application. Instead, the browser will open the authorization request URI and the request is sent from there to the account server.

Typically, your application can provide this URI to the user as a link to select or via an email.

EnvironmentAPI Base URIWeb Site Login URL
Developerhttps://account-d.docusign.com``/oauth/authhttps://account-d.docusign.com
Productionhttps://account.docusign.com/oauth/authhttps://account.docusign.com

The authorization request includes several parameters used with the base URL to configure specific authentication options. The following parameters are required:

ParameterDescription
response_typeThe type of grant to be used. This value should be code.
Note: Your integration’s settings in the Apps and Keys page should be configured to Authorization Code Grant, or you may receive an error.
scopeThe scope of the permissions being requested for the client. Typically, for users explicitly using individual consent, this value should be signature%20impersonation. If your application needs additional scopes, add them to the list.
client_idYour application’s integration key.
redirect_uriThe URI to which Docusign will redirect the browser after authorization has been granted by the user. Typically, this will simply be a page thanking the user for granting consent. This page should be provided by the application.
The redirect URI must match one of those pre-registered for the integration key in your Docusign account. This determines where to redirect the user after they successfully authenticate.
Note: If you include query parameters in your redirect URI, the redirect must be url-encoded.

Your application should open the resulting URI in a web browser to initiate the authentication process. You can test the process by pasting your URI string into a browser window.

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

If the user hasn’t already given consent (or if consent has been revoked by the user or an admin) they are notified that they must give consent to the application for the requested scopes.

After the user chooses Accept, consent is granted. The Docusign authentication service verifies that the client application is valid and has access to the requested scope. If so, it redirects the access token to the provided callback URI in a hash fragment.

Once a user has granted consent to an application, they will no longer be prompted to do so again unless consent is revoked.

Authorization Code Grant permission screen

Next steps

  • Every Docusign workflow requires that your user grant explicit consent for your application to act on their behalf. See Obtain and revoke consent for details and a description of each way to get consent from your users.
  • Learn more about authentication.
  • See the list of scopes.