From the Trenches: But I already gave consent!
Troubleshoot application consent errors in your Docusign integrations arising from mismatched scopes and user IDs.
Many developers are migrating their integrations from basic authentication to OAuth2.0 for its security benefits and to stay compliant with Docusign’s API requirements. (Check out Larry’s Blog post regarding OAuth2.0 - October 2022: OAuth 2.0 required for all Docusign API applications).
An important step of OAuth 2.0 is having the user grant consent for the integration to make API calls. Users may experience the following error message after granting consent and attempting to retrieve an access token: "Consent required". This can be a frustrating error to come across when you know that you have granted consent using the consent URL and are logging in using the correct email address.
Why can’t I grant consent?
The cause of this behavior is not that consent is not working; it’s either that the user has multiple Docusign memberships with different Docusign accounts or the scopes in the consent URL do not align with the scopes the application requires. Let’s address the mismatched scopes first.
When granting consent, you specify the authentication scopes the user allows for the integration. It is imperative that the user grants consent for the same scopes that the application will need. For example, if your application uses JWT for authentication and impersonation, you will need to grant consent for the integration to use the impersonation scope. If you do not add impersonation to the consent scopes, you will end up with the “Consent required” error.
The second cause of this error is not as straightforward. As you may be aware, a user can have a membership with many different Docusign accounts. Let’s say, for example, there are two Docusign accounts; account_a and account_b. Both accounts can send a membership invite to a user with the email: test@example.com.
If the user, test@example.com, uses the same password for each account, they will be able to switch between accounts within the Docusign Web Portal and grant consent for integrations without error. This is because the user will have one unique user ID.
If the user creates two different passwords for account_a and account_b, then this will cause Docusign to create two user IDs associated with the email: one for each account. This can cause potential issues if the user wants to grant consent for an integration using account_a, but instead they provide the password used for account_b. Then consent will be granted, but for the incorrect user ID.
This is when the user will experience the error introduced at the beginning: they have already granted consent, but the integration is running into consent errors when requesting an access token.
How can I make sure my users are using the correct password?
Now that you understand the cause of this error, you can move towards resolving the issue. To resolve this error, the user must use the correct password for the desired account when granting consent. This can be confirmed by following the steps outlined below:
If the user does not know their password for the desired account, they must request an admin on the account to reset their password.
As an admin you can log into the Docusign Web Portal and navigate to Settings > USERS AND GROUPS/Users, locate the user, and then select ACTIONS > Reset Password..
Once the user receives the email to reset their password, instruct them to make a unique password.
After the user resets their password, attempt to grant consent again, making sure to use this new password they have created.
Now that consent has been granted for the correct userID, attempt to retrieve an accessToken for authentication.
As a helpful tip, you can recommend the user to use the same password for each Docusign account. This will avoid any confusion in the future, as the user will now have one userID associated with their email address. If a user has memberships with different accounts, they will be prompted to choose which account they will want to grant consent for. Make sure to choose the account that you want to link to the integration.
Conclusion
OAuth2.0 can seem confusing at times with consent errors being thrown regardless of whether the user has already granted consent using their email. In this example, it’s good to remind yourself of the tried and true methods of troubleshooting, reset the user’s password, and try again!
Troubleshooting error codes can sometimes be not so intuitive; if you ever need clarification, feel free to reach out to our Support team and open up a case. I, or anyone on my team, will be happy to assist.
Additional resources
Hunter Wiegand joined Docusign’s Developer Support team in 2021 with a focus on assisting customers with API driven issues.
Related posts
Discover what's new with Docusign IAM or start with eSignature for free
