August 28, 2026
The Short Answer: Run Old and New Credentials in Parallel
Yes, you can rotate DocuSign API credentials without interrupting a single envelope — but not by swapping a value in place. DocuSign does not expose a "rotate this credential" endpoint, and it does not need one, because its OAuth model already supports overlap: an integration key can hold more than one RSA key pair at a time (the JWT Grant documentation caps this at five per integration key), and an account can carry multiple integration keys. Zero downtime comes from using that overlap deliberately: create the replacement credential while the current one is still valid, mint tokens from either one behind a flag in your token service, shift traffic gradually, and retire the old credential only after a clean soak period.
Two token-lifecycle properties keep the blast radius small. Access tokens last one to eight hours by grant type, so your application already re-issues tokens continuously — rotation plugs into that code path. And the credential layer (Apps and Keys) is decoupled from token issuance: cutover is your token service changing which private key or secret it signs with.
What You Are Actually Rotating: Integration Keys, Secrets, and RSA Key Pairs
"Integration key" gets used loosely, but DocuSign's credential model has three layers, and each rotates differently.
The integration key itself is the public client ID that identifies your application. It is created on the account's Apps and Keys page and links to the app's configuration: redirect URIs, scopes, and the authentication material below. It is not a secret — it appears in authorization URLs and consent screens — so "rotating the integration key" means rotating what is attached to it.
For JWT Grant — the typical choice for service-to-service integrations — the secret material is an RSA key pair attached to the integration key. Your application signs a JWT assertion with the private key (carrying iss = the integration key, sub = the impersonated user's GUID, aud = the OAuth base path, typically the signature impersonation scopes) and exchanges it at the token endpoint.
For Authorization Code Grant, the secret material is the client secret, generated on the same page. The SDK documentation notes the secret is displayed only once and that if you forget it you generate a new one — the rotation lever for ACG-based integrations.
Decide up front which layer you are rotating: the RSA key pair (JWT shops), the client secret (ACG shops), or the entire integration key (breach response). The phased workflow is the same.
Why DocuSign's Token Lifecycle Buys You Zero Downtime
Three documented behaviors make gradual cutover safe:
- Access tokens are short-lived. Per DocuSign's developer guidance, access tokens last one to eight hours depending on the grant type — JWT Grant tokens sit at the short end (about one hour), and Authorization Code Grant responses show
expires_inof 28800 seconds with an accompanying refresh token. A stale token hurts you for minutes, not days. - Refresh tokens live in days, not hours. Refresh tokens last 30 days by default; with the
extendedscope (Authorization Code Grant only), each refresh issues a new one valid for another 30 days. Decide whether your rotation forces a re-consent or lets old refresh chains expire. - 401s are a recovery signal, not a failure. DocuSign's error-handling guidance recommends treating a 401 as a trigger to obtain a fresh token and retry. If your client already does this, a botched cutover degrades to a few extra token requests, not an outage.
Also respect the hourly limits on /oauth/userinfo requests per user ID and integration key. For how these operational limits interact with plan pricing, see our API rate limits and pricing review.
The Phased Rotation Workflow
The phase teams skip is 4. The one that hurts most when skipped is 0: undocumented cron jobs and forgotten Zapier-style automations are why "we rotated the key and three workflows died two weeks later" stories exist. The credential-hygiene arguments in our guide to e-signature cybersecurity risks apply here too.
Rotate Within One Integration Key or Create a New One
Two viable models exist, and choosing between them is the main strategic decision.
Model A — new RSA key pair on the same integration key. Because OAuth consent is granted to the client ID, replacing the key pair requires no re-consent. The documented cap is five RSA key pairs per integration key, so you can add the new pair while the old one still works; if you are at the cap, delete dead pairs first. Cutover is your token service switching which private key it signs with.
Model B — a new integration key entirely. The right response to a compromised credential or a configuration rebuild, and DocuSign supports multiple integration keys per account. The cost: consent is granted per client ID, so the new key needs fresh consent — JWT Grant without it returns the consent_required error, and users or an administrator must re-authorize the new app before impersonation works. Budget for that in Phase 2.
Rotation-Day Checklist and Error Handling
Before touching the Apps and Keys page, work through this checklist:
- The Phase 0 dependency map is current and countersigned.
- The new credential is in the secret manager, access restricted to the token service.
- The feature flag supports per-request credential selection, not just a global switch.
- Alerting covers 401 rates, token-endpoint errors, and envelope-completion lag.
- The rollback path is documented: flip the flag back to the old credential.
- A calendar reminder exists for the soak review.
A JWT Grant token request in its minimal form — placeholders only, never real credentials:
```bash
curl --data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={$JWT}" \
--request POST https://account.docusign.com/oauth/token
```
The assertion your application signs carries these claims:
```json
{
"iss": "YOUR_INTEGRATION_KEY",
"sub": "YOUR_IMPERSONATED_USER_ID",
"aud": "account.docusign.com",
"iat": {$IAT},
"exp": {$IAT_PLUS_6000},
"scope": "signature impersonation"
}
```
Two behaviors are worth verifying in your sandbox first: whether an access token minted from the old credential keeps working until it expires after you delete the old key pair or secret, and whether a previously generated client secret remains valid after you generate a new one on the same integration key. The documentation covers the mechanics but not either edge case — treat sandbox confirmation as part of Phase 2.
When Rotation Cycles Expose Platform Limits: Nota Sign
If credential rotation is a recurring tax on your engineering team, reassess the platform itself — our guide to what DocuSign is and when to compare alternatives frames that decision. Nota Sign, FaDaDa's e-signature platform for international business, is API-first by design: consecutive years at the top of IDC's China e-signature software rankings, legal coverage across 100+ countries and regions, and APAC identity layers — iAM Smart, Singpass, SES/AES/QES — built in rather than bolted on, so credential hygiene stays a routine, not a fire drill. Developers can go straight to our walkthrough of iD-One and iCorp-One identity integrations or the China eSignature API guide. No per-seat fees means small teams scale without seat-count anxiety; mid-market and enterprise buyers negotiate tailored plans. To scope rotation-friendly credentials from day one, start the conversation.
