2026年8月28日
简短答案：新旧凭据并行运行
可以：在不中断任何一个签署包的情况下轮换 DocuSign API 凭据——但方式不是原地替换某个值。DocuSign 没有提供「轮换此凭据」的接口，也不需要提供，因为它的 OAuth 模型本身就支持重叠期：一个集成密钥可以同时挂载多个 RSA 密钥对（JWT Grant 文档给出的上限是每个集成密钥 5 个），一个账号也可以持有多个集成密钥。零停机来自对这种重叠期的刻意利用：在旧凭据仍然有效时创建新凭据，让令牌服务在功能开关后同时支持用任意一套凭据签发令牌，逐步切流，待观察期干净无告警后再退役旧凭据。
令牌生命周期的两个特性把爆炸半径压到很小。访问令牌按授权类型存活一到八小时，所以你的应用本来就在持续重新签发令牌——轮换正好接入这条既有代码路径。而凭据层（Apps and Keys 页面）与令牌签发是解耦的：切换动作只是你的令牌服务改用哪把私钥或哪个密钥来签名。
你真正在轮换什么：集成密钥、客户端密钥与 RSA 密钥对
「集成密钥」这个词经常被混用，但 DocuSign 的凭据模型有三层，每一层的轮换方式都不同。
集成密钥本身是标识你应用的公开客户端 ID。它在账号的 Apps and Keys 页面创建，并关联到应用配置：重定向 URI、scope，以及下面要说的认证材料。它不是秘密——它会出现在授权 URL 和授权同意页面上——所以「轮换集成密钥」实际指的是轮换挂在它下面的东西。
对于 JWT Grant——服务间集成的典型选择——秘密材料是挂在集成密钥下的 RSA 密钥对。你的应用用私钥签署一个 JWT 断言（携带 iss = 集成密钥、sub = 被模拟用户的 GUID、aud = OAuth 基础路径，scope 通常是 signature impersonation），再到令牌端点换发令牌。
对于 Authorization Code Grant，秘密材料是在同一页面生成的客户端密钥。SDK 文档注明该密钥只显示一次，忘了就只能重新生成——这正是基于 ACG 的集成的轮换抓手。
动手之前先想清楚你要轮换哪一层：RSA 密钥对（用 JWT 的团队）、客户端密钥（用 ACG 的团队），还是整个集成密钥（凭据泄露后的应急响应）。分阶段工作流是同一套。
为什么 DocuSign 的令牌生命周期让你实现零停机
三个有文档可查的行为让渐进切换足够安全：
- 访问令牌短命。 按 DocuSign 开发者指南，访问令牌按授权类型存活一到八小时——JWT Grant 令牌在短端（约一小时），Authorization Code Grant 响应中的
expires_in为 28800 秒并附带刷新令牌。一个过期令牌给你造成的损失以分钟计，而不是以天计。 - 刷新令牌以天计，不以小时计。 刷新令牌默认存活 30 天；启用
extendedscope 后（仅 Authorization Code Grant），每次刷新都会换发一个再续 30 天的新令牌。你需要决定轮换是强制重新授权同意，还是放任旧的刷新链自然过期。 - 401 是恢复信号，不是故障。 DocuSign 的错误处理指南建议把 401 当作触发条件：获取新令牌并重试。如果你的客户端已经是这么做的，一次搞砸的切换只会退化成多几次令牌请求，而不是一场停机。
同时要留意按用户 ID 和集成密钥计的 /oauth/userinfo 每小时请求限额。这些运营层面的限额与套餐定价如何相互影响，可参见我们的 API 速率限制与定价评测。
分阶段轮换工作流
团队最常跳过的是第 4 阶段，而跳过后最疼的是第 0 阶段：没有文档的定时任务和被遗忘的 Zapier 式自动化，正是「我们轮换了密钥，两周后三条工作流死了」这类故事的来源。我们的电子签名网络安全风险指南里的凭据卫生论点在这里同样适用。
在同一集成密钥内轮换，还是新建集成密钥
两种模式都可行，二者之间的取舍是主要的战略决策。
模式 A——在同一集成密钥上新增 RSA 密钥对。 因为 OAuth 授权同意是授予客户端 ID 的，替换密钥对无需重新授权。文档记载的上限是每个集成密钥 5 个 RSA 密钥对，所以可以在旧密钥对仍可用时新增；若已到上限，先删掉废弃的密钥对。切换动作就是你的令牌服务改用哪把私钥签名。
模式 B——整体新建集成密钥。 这是凭据泄露或配置重建时的正确应对方式，DocuSign 支持每个账号持有多个集成密钥。代价是：授权同意按客户端 ID 授予，新密钥需要新的授权同意——没有它，JWT Grant 会返回 consent_required 错误，必须由用户或管理员重新授权新应用，模拟调用才能工作。把这部分预算排进第 2 阶段。
轮换日检查清单与错误处理
在碰 Apps and Keys 页面之前，先走完这份清单：
- 第 0 阶段的依赖关系图是最新的，且已会签确认。
- 新凭据已入密钥管理器，访问权限仅授予令牌服务。
- 功能开关支持按请求选择凭据，而不是只有一个全局开关。
- 告警覆盖 401 比率、令牌端点报错和签署包完成延迟。
- 回滚路径已写入文档：把开关拨回旧凭据。
- 日历里已有观察期复盘的提醒。
一个最简形式的 JWT Grant 令牌请求——仅占位符，切勿填入真实凭据：
```bash
curl --data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={$JWT}" \
--request POST https://account.docusign.com/oauth/token
```
你的应用签署的断言携带以下声明：
```json
{
"iss": "YOUR_INTEGRATION_KEY",
"sub": "YOUR_IMPERSONATED_USER_ID",
"aud": "account.docusign.com",
"iat": {$IAT},
"exp": {$IAT_PLUS_6000},
"scope": "signature impersonation"
}
```
有两个行为值得先在沙箱里验证：删除旧密钥对或旧密钥之后，由旧凭据签发的访问令牌是否一直有效到自然过期；在同一集成密钥上重新生成客户端密钥后，旧密钥是否仍然有效。文档讲了机制，但没有覆盖这两个边缘场景——把沙箱确认当作第 2 阶段的一部分。
当轮换周期暴露出平台瓶颈：Nota Sign
如果凭据轮换对你的工程团队来说是一笔反复缴纳的税，是时候重新评估平台本身了——我们的 DocuSign 是什么、何时该对比替代方案指南 给出了这个决策的框架。Nota Sign 是FaDaDa面向国际业务的电子签名平台，从设计上坚持 API 优先：连续多年位居 IDC 中国电子签名软件排名第一，法律覆盖横跨 100 多个国家和地区，亚太身份认证能力——iAM Smart、Singpass、SES/AES/QES——原生内置而非事后拼接，凭据管理因此保持日常化，而不是一次次救火。开发者可以直接阅读我们的 iD-One 与 iCorp-One 身份集成实践，或中国电子签名 API 指南。不按席位收费，意味着小团队扩张不必为席位数焦虑；中端市场与企业客户可洽谈定制方案。想从第一天起就规划对轮换友好的凭据体系，开启对话。
