From the Trenches: Requirements for using admin consent
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.
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.
Requirement 3: Consent granted by an organization administrator
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.
