From the Trenches: Requirements for using admin consent

•

Summary•3 min read

When considering using admin consent in your app, consider these requirements for it to work for you.

Requirement 1: Having an organization
Requirement 2: Having a claimed domain
Requirement 3: Consent granted by an organization administrator
Additional resources

Requirement 1: Having an organization
Requirement 2: Having a claimed domain
Requirement 3: Consent granted by an organization administrator
Additional resources

The Docusign user for whom an integration is obtaining an access token must provide consent for the set of scopes (permissions) that the integration is requesting. If you attempt to obtain an access token for a user who has not provided consent for the requested scopes, you will receive an error like consent_required. Consent is typically only needed once and is applied to the user unless the user manually revokes the consent on the Connected Apps page

One approach is to have each integration user provide individual consent. However, you may notice an option for admin consent that could allow you to grant consent for multiple users at once (in particular, it grants consent for all domain users, but I’ll go into that more later).

While admin consent is a powerful approach that could be convenient for integration users, it’s important to understand the requirements that need to be met in order for a user to be able to grant admin consent on behalf of users.

Requirement 1: Having an organization

In order to use admin consent, the set of users for whom consent is being granted must be part of an organization. In Docusign terminology, an organization is where you can perform centralized management of your users’ multiple eSignature accounts and which users have membership on which eSignature accounts. You can also manage SSO configurations and claimed domains within organization management.

From the Trenches: Considerations when including an admin consent option in your app

Not every Docusign user is part of an organization and there are requirements for which eSignature account plans are eligible to be managed with organization management. If you are trying to use admin consent for a user that is not part of an organization, admin consent won’t work.

If an organization is set up for an account, a user that is added as an organization administrator can access organization management.

Requirement 2: Having a claimed domain

As alluded to previously, admin consent grants consent for domain users within your organization. This means consent will be granted only for users whose email address domain matches one of your organization’s claimed domains. By claiming a domain, it proves that your company owns that domain. Claiming a domain is performed within organization management.

This means that if some of your users in your organization have an email address domain that is not a claimed domain, those users would not have consent applied to them through admin consent.

When performing admin consent for external applications, the integration would redirect a user to a Docusign login screen. For admin consent, the Docusign user that logs in at this point needs to be an organization administrator. eSignature administrators of an individual account within an organization may not be an organization administrator for the organization of which that eSignature account is a member.