How to Set Up a DocuSign Integration Key and Connect It to Salesforce

What You Need Before You Start

• A free DocuSign developer account from developers.docusign.com; it lives in the demo environment (account-d.docusign.com, https://demo.docusign.net/restapi).
• Admin rights on that DocuSign account. The Apps and Keys page is admin-only and invisible to everyone else.
• A Salesforce sandbox or Developer Edition org where you are a System Administrator.
• A password manager open and ready; DocuSign shows the RSA private key exactly once.
• OpenSSL and Java keytool if you will import the private key into Salesforce (.key to .pem to .p12 to .jks).
• About 45 minutes, plus 5 to 10 minutes of propagation delay after redirect URI changes.

Step 1: Create a DocuSign Developer Account

Go to developers.docusign.com and click Create Developer Account. This provisions a free account in DocuSign's demo environment, a full parallel universe: OAuth logins go to account-d.docusign.com, API calls to https://demo.docusign.net/restapi, and nothing you create here exists in production. User IDs, account IDs, integration keys, redirect URI lists, and JWT consents are all environment-specific, and none of it migrates at go-live.

Step 2: Create the Integration Key on Apps and Keys

Log in to the demo account, open Settings from the top menu (this is eSignature Admin), then click Apps and Keys under INTEGRATIONS in the left nav. If the page is missing, you are not an account admin. Fix that first.

• Copy the three values in the My Account Information panel at the top: User ID (a GUID that becomes the JWT sub claim), API Account ID (used in every REST path), and Account Base URI (https://demo.docusign.net in demo).
• Click the add button, typically labeled ADD APP / INTEGRATION KEY, name the app something like Salesforce JWT Service, and create it. You land on the app configuration page.
• The Integration Key appears immediately: a GUID serving as your OAuth client_id, not secret, visible forever. The frantic copying comes next.

Step 3: Generate the RSA Keypair and Register Redirect URIs

• In the Authentication section under Service Integration, click + GENERATE RSA. A modal shows the public and private key in plain text one time only. Copy both immediately; there is no reveal button, and after the modal closes only the keypair ID remains. Treat the private key like a production password from this second onward: no email, no Slack, no spreadsheet.
• Only click + ADD SECRET KEY if you need browser-flow Authorization Code Grant; the JWT flow uses no client secret.
• Under Additional settings, click ADD URI next to Redirect URIs. Matching is exact, character for character, fragments (#) are forbidden, and the runtime redirect_uri must be URL-encoded. Even the JWT consent URL needs a registered redirect URI, although its auth code is thrown away.
• For the managed package, register https://<domainName>.my.salesforce.com/apex/dfsle__completeoauth and https://<domainName>.my.salesforce.com/services/authcallback/DocusignAuthProvider. Save, then allow 5 to 10 minutes for changes to propagate.

Step 4: Grant One-Time Consent for the JWT Flow

The JWT grant lets a server act as a user, and that user must consent once per environment and scope set. Have them open https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=YOUR_INTEGRATION_KEY&redirect_uri=YOUR_REGISTERED_REDIRECT_URI, log in, and grant access. Both scopes are mandatory, and omitting impersonation is the number one cause of consent_required. Consent persists until revoked or until you request new scopes, and demo consent never carries to production.

If the client runs a DocuSign Organization with the Access Management with SSO plan feature and a claimed email domain, an org admin can consent for everyone: log in to admin.docusign.com (DocuSign Admin, not eSignature Settings), open Connected Apps, click Authorize Application, pick the integration key, and enter the scopes space-delimited as signature impersonation.

Step 5: Connect the Managed Package in Salesforce

For standard sending, buttons, and status writeback, do not hand-roll anything. Install DocuSign Apps Launcher (Apex namespace dfsle) from AppExchange. The legacy dsfs package is de-listed and stops working on October 16, 2026, so no new build should touch it.

• Open the Docusign Setup tab in the Docusign Apps Launcher app. The default login button connects a production account; the section beneath it connects a demo developer account, which is what you want right now.
• Log in as a user who is both a DocuSign account admin and a Salesforce System Administrator. That user becomes the integration user; across our 22 projects we always make it a dedicated service account.
• Approve the Salesforce-side OAuth so DocuSign Connect can write statuses back to records: Salesforce Setup > Connected Apps OAuth Usage > find the DocuSign app > Install.

The package manages its own integration key after this connect. Steps 2 through 4 exist for custom API work outside the package: Apex callouts, middleware, scheduled jobs.

Step 6: Wire the Custom Key with an External Credential and Named Credential

• Convert the private key: save it as .pem, run openssl pkcs12 -export to get a .p12, then keytool -importkeystore to a .jks. Import it via Setup > Certificate and Key Management > Import from Keystore.
• Create an External Credential: Authentication Protocol OAuth 2.0, Flow Type JWT Bearer Flow, Identity Provider URL https://account-d.docusign.com/oauth/token, JWT Expiration 3600, signing certificate set to the one you imported.
• Set the claims exactly: iss = your integration key, sub = the User ID GUID from Step 2, aud = account-d.docusign.com with no https:// and no trailing slash, scope = signature impersonation. The bare-host aud rule is the most common thing to get wrong.
• Create a Named Credential pointing at https://demo.docusign.net/restapi, link the External Credential, and grant the integration user access to the External Credential Principal via a permission set.
• No Auth. Provider is needed; those serve browser-flow Authorization Code Grant. If you build one later: type OpenID Connect, add openid to Default Scopes, uncheck PKCE, and register the generated callback URL as a DocuSign redirect URI.

Step 7: Smoke Test the Whole Chain

• Confirm identity first: GET https://account-d.docusign.com/oauth/userinfo with your access token returns your accounts with account_id and base_uri. Check they match the values from Step 2; this endpoint also resolves the production base URI later.
• Then hit the eSignature API: GET https://demo.docusign.net/restapi/v2.1/accounts/YOUR_API_ACCOUNT_ID/envelopes?from_date=2026-01-01. A 200 with an envelopes array, even empty, proves key, keypair, consent, and credential end to end. From Salesforce, run the same call in Anonymous Apex through the Named Credential.
• JWT access tokens live exactly 3600 seconds with no refresh token; sign a fresh assertion whenever needed, ideally about 15 minutes before expiry. Never poll the same envelope's status more than once per 15 minutes, an API terms violation in production; use DocuSign Connect webhooks instead.

Common Errors and How to Fix Them

• consent_required on POST /oauth/token: the user never consented in this environment, the consent URL omitted a scope, or they consented as a different DocuSign user ID (one email across multiple accounts creates multiple user IDs). Fix: reopen the consent URL with scope=signature%20impersonation in the matching environment as the correct user.
• invalid_grant with issuer_not_found: the key in iss does not exist in the environment your aud and token endpoint point at, classic when a demo key hits account.docusign.com before go-live. Fix: match aud, token URL, and key environment.
• invalid_grant with user_not_found: the sub GUID does not exist in that environment; demo User IDs differ from production. Fix: copy the User ID from the target environment's Apps and Keys page.
• invalid_grant with everything looking correct: check aud. It must be the bare host account-d.docusign.com or account.docusign.com, no https://, no trailing slash, even though the token POST goes to the full https URL.
• invalid_grant with no_valid_keys_or_signatures: the JWT signature matches no RSA keypair on the key, usually mangled PEM newlines or a deleted keypair. Fix: regenerate the keypair, save the private key with its line breaks intact, retry.
• Browser page The redirect URI is not registered properly with Docusign: the runtime redirect_uri does not exactly match a registered URI, contains a # fragment, or the Salesforce URIs are missing. Fix: Apps and Keys > Actions > Edit, add the URI, wait 5 to 10 minutes.
• PARTNER_AUTHENTICATION_FAILED, The specified Integrator Key was not found or is disabled: you are calling production with a demo-only key, or mixing a token from one environment with API calls to the other. Fix: complete go-live, or align auth environment and base URI via GET /oauth/userinfo.
• DocuSign Apps Launcher silently disconnected after a sandbox refresh: open https://<domain>.visualforce.com/apex/TroubleShooting and disconnect, then reconnect DocuSign.

Security Checklist Before You Ship

• The RSA private key lives only in your secret manager and Salesforce's certificate store; anyone holding it can mint tokens as your consented user.
• Request only signature and impersonation. Product scopes like click.manage force re-consent when added later, so treat scope additions as planned changes.
• Impersonate a dedicated service account, not a human admin whose deactivation would strand every envelope in flight.
• Keep demo and production credentials in separate secret entries; nothing migrates at go-live, including consents, and re-check the promoted key's redirect URI list yourself.
• Audit the redirect URI list quarterly and delete anything unused; every registered URI is a place an auth code may land.
• Never log the JWT assertion or access token in Apex debug logs, and keep endpoints in the Named Credential, not hardcoded in classes.

Where This Fits in the Full DocuSign Build

Everything above happens in demo; production sits behind a promotion wall called go-live, which got dramatically easier on October 3, 2025 when the old 20-successful-API-calls requirement was eliminated. On the demo Apps and Keys page you edit the key, choose an integration type, enter production account details, and validation approves instantly, flags a manual review that typically resolves within 48 hours, or rejects. The type selection is irreversible once under review, and picking Public integration when you meant Private custom integration can trigger unexpected billing. Disable pop-up blockers; the flow requires logging in as an admin of the production account, which cannot be a trial. The DocuSign Developer Console at devconsole.docusign.com (open beta) now manages demo and production keys from one account with one-click promotion.

The integration key is step one of a longer build: templates, merge fields, Connect writeback, Flow-triggered sending, and the production cutover, all covered in our technical guide at cloudsheer.com/integrations/docusign/technical-guide. If you build with Claude Code, our free skill packages this checklist: npx skills add shivamgoel-cloudsheer/Claude-skills --skill docusign-salesforce.

How Cloudsheer Can Help

Cloudsheer has delivered DocuSign and Salesforce integrations across 22 client projects, from managed-package rollouts to custom JWT service integrations pushing thousands of envelopes a month. We have hit every error above at least once on a client clock, which is why our builds start with the credential layer done right: dedicated integration user, scoped one-time consent, secrets in a vault, and a passing smoke test before any business logic ships.

If your team is staring at consent_required the night before a launch, or planning the forced migration off the retired dsfs package before October 2026, we can save you weeks of trial and error. Book a free discovery call at cal.com/cloudsheer-consulting/30min.