How to obtain admin consent for external applications | Docusign

Integration developers can obtain consent from another organization’s users (every user who is a member of that organization’s reserved domains) by having an admin of that organization grant consent on their users’ behalf.

Step 1. Construct the Docusign authorization URI

To prompt an organization admin to grant consent to your integration, you must construct an authorization URI and send the admin’s browser to it. Your authorization URI can enable the organization admin to grant consent on behalf of the users in every organization that the admin administers.

Although the admin consent flow for external apps calls into the Docusign authentication service, it is used for the express intent of granting consent rather than getting an access token.

To secure admin consent in this step, the application seeking admin consent must direct the organization admin to an authorization service URI with a scope header value of openid and an additional admin_consent_scope parameter that holds the list of scopes that are requested for each user in the organization.

For the developer environment, the base URI for the authorization request is https://account-d.docusign.com
For the production platform, the base URI is https://account.docusign.com/oauth/auth

The authorization request includes several parameters used in conjunction with the base URI that configure specific authentication options. The following parameters are required:

Parameter	Description
`response_type`	The type of response to be returned. Either response type, `code` or `token`, can be used for admin consent. Possible values are: `code`, for the Authorization Code Grant. `token`, for the Implicit Grant.
`scope`	When using admin consent, the value of the scope parameter should be `openid`. This causes the organization IDs of the organizations who are consenting to the requested admin scopes on behalf of their members to be recorded in the response.
`client_id`	The application’s integration key.
`redirect_uri`	The 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 pre-registered for the integration key in your Docusign account. This determines where to redirect the user after they successfully authenticate.
`admin_consent_scope`	The scope of the permissions being requested for the application from each user in the organization. Formatted in a space-separated list of the following values: `signature` — Allows your application to create and send envelopes, and obtain links for starting signing sessions. `extended` — Issues your application a refresh token that can be used any number of times. This scope may only be granted in the Authorization Code flow. `impersonation` — Allows your application to access a user’s account and act on their behalf even when that user is not present. This scope is only used by JWT authentication. Note: Encode the space character as `%20` in URIs.

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

Next, the organization admin uses the URI constructed in Step 1 to log in to Docusign. If successful, they are prompted to grant consent for the requested scopes on behalf of the users in their organization(s).

Users in each selected organization can have consent granted on their behalf by the admin when the Accept button is clicked.

After obtaining consent, you can use a supported OAuth authentication flow to get an access token and make API calls. When you obtain an access token, if the openid scope was requested, your response will also contain an ID token. This token contains information about the identity of the admin that consented and is the only mechanism you can use to retrieve the list of consented organization IDs (which are listed in the coid property).

The ID token has no system function and is not used to authenticate API requests; its only purpose is to hold information on the consenting admin and organizations.

Each ID token contains the following fields:

Parameter	Description
`aud`	The integration key (also known as client ID) of the application.
`iat`	The DateTime when the ID token was issued, in Unix epoch format.
`exp`	The DateTime when the ID token will expire, in Unix epoch format.
`iss`	The URI of the authentication service instance to be used. For demo environments, use `account-d.docusign.com`. For production environments, use `account.docusign.com`.
`sub`	The user ID of the admin granting consent for the organization users.
`siteid`	Identifies the Docusign server used. NA1 NA2 NA3 EU AU CA
`amr`	Describes how the user authenticated. Typically, this will always be `interactive`.
`auth_time`	The Unix epoch DateTime when the ID token was created.
`coid`	Contains the list of organization IDs for the organizations whose admin has granted consent for Docusign to act on their behalf.

Screenshot of an admin being asked to grant consent

Example ID token

{
    "aud": "feb2892b-xxxx-xxxx-xxxx-8a9a172c86ac",
    "iat": 1520289199,
    "exp": 1522881199,
    "iss": "https://integration.domain.com/",
    "sub": "b5ce2297-xxxx-xxxx-xxxx-29f543763505",
    "siteid": 1,
    "amr": [
        "interactive"
    ],
    "auth_time": 1520289165,
    "coid": [
        "c0e33051-xxxx-xxxx-xxxx-768841b64a66",
        "7b896d88-xxxx-xxxx-xxxx-1a327b125995"
    ]
}

Next steps

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

Step 1. Construct the Docusign authorization URI

Step 2. Obtain consent

Next steps