DocuSign API "CONSENT_REQUIRED" on JWT grant - how to fix

Fix DocuSign "CONSENT_REQUIRED" on the JWT grant

TL;DR

Get consent granted for your integration key, then retry. The JWT flow lets your app act as a user, so DocuSign blocks it until the user (or an org admin) explicitly approves. Have the user open the consent URL once, or get admin-level consent for the whole account, and the same JWT request will succeed.

{
  "error": "consent_required"
}

1. Confirm which environment your code targets. Demo uses account-d.docusign.com; production uses account.docusign.com. Consent granted on one never covers the other. Expected: you can name the exact host your JWT request hits.

2. Build the consent URL for that environment: the oauth auth endpoint on your host with response_type=code, scope set to signature plus impersonation, and your integration key and registered redirect URI filled in. Have the impersonated user open it in a browser and accept. Expected: DocuSign confirms access and redirects back.

3. For many users, ask an org admin to grant consent once in the Admin console under Connected Apps. Expected: every user under the account can use the JWT flow with no individual clicks.

4. Retry the JWT grant with no other changes. Expected: a 200 response carrying an access token instead of consent_required.

Use this when

• the first JWT token request fails with consent_required
• the integration key and RSA keypair are correct but auth still fails
• you moved from demo to production (or vice versa) and auth broke
• a new user was added and only their requests fail

Not for this skill when

• you are using Authorization Code Grant (consent is interactive there by design)
• the error is a key or grant error rather than consent (a credential problem, not consent)
• consent was granted and the same error persists (recheck the environment mismatch in step 1)

Variant phrasings

• docusign jwt consent_required how to grant consent
• docusign impersonation scope consent admin approval
• docusign oauth consent required service integration
• docusign jwt flow first time setup consent

Why it happens

JWT impersonation lets an app act as any consented user without them present, so DocuSign requires explicit opt-in before the first use. The API cannot grant consent for you; it has to happen in a browser session (or by an admin). New keys, new users, and environment switches all reset the requirement.

Edge cases

• The redirect URI in the consent URL must exactly match a URI registered on the integration key.
• Consent is per user per key per environment. Three dimensions, all must line up.
• If the user is later deactivated, consent stops working and the error can look identical.
• Admin consent needs actual org admin rights; account admins on some plans cannot grant it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_F2azPp65vOGKeIRJKANzdQ