DocuSign API JWT Grant Flow：服务集成认证指南

JWT Grant Flow 是 DocuSign 面向服务集成的 OAuth 2.0 认证方式：自动化后端以某个特定用户的身份调用 DocuSign API，而该用户无需登录。你注册一个 integration key，在 Apps and Keys 页面添加 RSA 公钥，取得被代行用户的一次性授权同意，然后用私钥签出一个 JWT，POST 到 DocuSign 的 /oauth/token 端点换取 access token。这个 token 有效期为一小时，该流程不会签发 refresh token；token 过期后，集成只需重新构建并签出一个新 JWT，再兑换一次即可。本指南覆盖每一步操作、授权同意规则、token 机制，以及如何在 JWT Grant 与 Authorization Code Grant 之间做选择。如果你刚接触这个平台，建议先找一篇 DocuSign API 通用入门教程热身，再深入认证细节。

JWT Grant Flow 为服务集成解决什么问题

DocuSign 的官方文档把集成分为两大家族。用户集成代表一个在场并登录的真实用户行事，通过 Authorization Code Grant 流程完成认证；服务集成则直接连接 DocuSign 账户，获得长期代行（impersonation，即以该用户身份行事）某个特定用户的权限，而该用户无需在场。

DocuSign 自己举的例子是：一个监控新员工入职的服务，自动从 HR 别名或经理账户发出入职文件，无需任何人为每位员工点一次"发送"。服务集成高度自动化、频繁调用平台、没有直接的用户交互——这正是 JWT Grant 为之设计的场景。

DocuSign 列出了该流程的具体优势：系统账户可以代表已授权组织中的任何用户执行操作，无论该用户是否在场；配合 DocuSign Admin，庞大的用户群体也变得可管理；RSA 密钥对提供强安全保障。代价同样真实存在：你的集成可能需要支持多条授权同意路径（管理员授权同意，加上域外人员的个人授权同意）；你必须查询并存储一个账户级用户 ID 才能获得通用账户访问权限；如果不使用 DocuSign SDK，还需要引入密码学库来构建 JWT。如果想从更宏观的角度评估自动化的价值，可以另行考察将电子签名 API 集成进业务软件的整体收益。

前置条件：integration key、redirect URI 与 RSA 密钥对

DocuSign 文档列出的 JWT Grant 前置条件归结为三项：

1. 一个 integration key，用于标识你的集成并关联其配置值，在 Apps and Keys 页面创建。
2. 一个注册到该 integration key 的 redirect URI。在 JWT 流程中，redirect URI 只在授权同意环节使用；送达它的授权码之后不会被使用。
3. 一对 RSA 密钥对。公钥加入集成的配置中，私钥留在你的应用一侧。

有两个细节值得提醒。第一，一个 integration key 最多支持五对 RSA 密钥对；如果已有五对，必须先删除一对才能新增。这个上限也是你的轮换预算：先添加替换用的新密钥，把代码切换过去，再退役旧密钥。第二，DocuSign 公开示例中使用的 RSA 密钥长度是 2048 位，私钥文件应放在密钥管理器里，而不是提交进代码仓库。

如何通过 JWT Grant 获取 access token：分步指南

第 1 步：请求授权同意。在任何 API 调用之前，你的应用将要代行的用户必须先授予权限。在浏览器中打开 DocuSign 的授权端点，参数带上你的 integration key 作为 client_id、申请的 scope，以及已注册的 redirect_uri。用户登录并点击接受后，你的应用即可通过 JWT Grant 代行该用户。返回到 redirect URI 的查询参数（包括 code 值）在 JWT 流程中不会被使用。

第 2 步：创建 JWT。用你的 integration key、被代行用户的用户 ID，以及对应环境的正确 audience 构建 assertion，然后用 RSA 私钥签名。下一节逐字段拆解。

第 3 步：用 JWT 兑换 access token。以 grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer POST 到 token 端点：

curl --data "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=YOUR_JSON_WEB_TOKEN" \

--request POST https://account-d.docusign.com/oauth/token

开发者（demo）环境的端点是 https://account-d.docusign.com/oauth/token；生产环境是 https://account.docusign.com/oauth/token。成功的响应中会包含你的 access token。

第 4 步：获取用户的 base URI。API 调用需要 access token，外加一个你所代行用户专属的 base URI。用 Bearer 授权头调用 /oauth/userinfo 端点，它会返回该用户所属的账户列表，从响应中取出 account_id 和 base_uri。DocuSign 对 /oauth/userinfo 按用户 ID 和按 integration key 设有每小时调用上限，因此应缓存这些值，而不是每次请求都调用该端点。

JWT assertion：header、claims 与签名

一个 DocuSign JWT 由三段 JSON 组成，编码后以句点分隔。header 指定算法：

{"alg": "RS256", "typ": "JWT"}

body 携带标识"谁在请求、代行谁"的 claims：

{"iss": "", "sub": "", "aud": "account-d.docusign.com",

"iat": , "exp": ,

"scope": "signature impersonation"}

逐字段说明：

• iss：你的 integration key，也叫 client ID。
• sub：被代行用户的用户 ID。
• aud：demo 环境为 account-d.docusign.com，生产环境为 account.docusign.com。
• iat 与 exp：签发时间和过期时间，均为 Unix 时间戳。DocuSign 示例中过期时间约为签发后一小时。
• scope：签署工作流使用 "signature impersonation"。

签名是对 base64url 编码后的 header 和 body 计算的 RSASHA256，使用你的 RSA 私钥。你可以用 JWT 库手工组装 assertion，也可以交给 DocuSign SDK 处理——官方 SDK 把整个兑换过程封装为一次请求调用。无论走哪条路，aud 不匹配（demo 与生产混用）或 assertion 未签名，都会在 token 端点失败。

还有一条规划提示：用于通用账户访问的账户级用户 ID，并不总是你一开始拿到的那个值。DocuSign 文档指出，获取它需要额外的 API 调用，或自行实现存储与查询逻辑，因此要为此预留一个小型的开通步骤。

授权同意：身份代行（impersonation）前的一次性门槛

授权同意（consent）是合法服务集成与未授权集成之间的分界线，DocuSign 对此态度严肃。文档给出两条路径。

个人授权同意：每位被代行的用户打开授权 URL、登录、点击接受。DocuSign 文档提到，接受之后用户的浏览器可能显示一个无法加载的页面；该提示可以忽略，直接关闭标签页即可。授权同意在被撤销前一直有效。

管理员授权同意：管理员可以通过 DocuSign Admin 为整个组织授予授权同意，既适用于内部应用，也适用于外部应用。由于并非所有与组织协作的人都在其域内或能访问 DocuSign Admin（DocuSign 自己举的例子是外包人员），集成通常需要同时支持管理员授权同意和个人授权同意。

授权同意还按环境分别授予。demo 环境的授权同意不会带入生产环境，切换到生产端点后需要重新完成授权同意步骤。

Token 有效期：一小时，无 refresh token

这正是从其他 OAuth 集成迁移过来的团队最容易意外的地方。通过 JWT Grant 签发的 access token 一小时后过期，且该流程不提供 refresh token。token 过期后，集成必须生成新 JWT 并兑换新 access token。实践上意味着：

• 把 token 请求当作日常操作，而非异常处理。每个被代行用户大约每小时取一次 token，是预期节奏。
• 在 access token 的有效期内缓存它；过期时用"重新请求 token"的重试来处理，而不是让业务交易失败。
• 每次都用当前 iat 构建新的 assertion，不要复用陈旧的 JWT。
• 保护好私钥。任何持有私钥的人都能代行该集成下所有已授权的用户——DocuSign 明确称之为"授予了高度信任"。还应叠加账户层防护，例如在集成涉及的账户上为签署人和管理员启用双重认证（2FA）。

认证流程选型：JWT Grant 与 Authorization Code Grant 对比

JWT Grant 不是进入 DocuSign API 的唯一大门，对交互式应用来说更是错的那扇门。静态 API key 不在 DocuSign 文档所列的认证选项之内，平台一律通过 OAuth 2.0 授权流程认证。因此实际决策是在 JWT Grant 与 Authorization Code Grant 之间：

流程	最适用场景	用户是否在场	凭据	refresh token
JWT Grant	服务集成、守护进程、定时任务、自动化后端	一次性授权同意后无需在场	RSA 私钥	无；每小时重新请求 token
Confidential Authorization Code Grant	有服务器、每个用户各自登录的 Web 应用	用户登录	client secret	有
Public Authorization Code Grant	移动应用与单页应用	用户登录	无 client secret	有

当所有操作都在系统账户或管理员登录名下运行，或你通过 DocuSign Admin 管理大量用户时，选 JWT Grant。当应用需要每个终端用户亲自登录、以本人身份操作时，选 Authorization Code Grant。DocuSign 在这一点上指引很明确：如果你的集成不需要代行权限或自动化操作，就改用 Authorization Code Grant。还有一条预算提示：认证设计也会影响成本，因为 token 的频繁兑换和 API 调用量都会直接反映到 DocuSign 的使用成本上。

服务集成 JWT Grant 实施检查清单

上线前，逐项过一遍这份清单：

• 已在 Apps and Keys 页面创建 integration key 和 redirect URI
• 已生成 RSA 密钥对（2048 位），公钥已上传，私钥存放在密钥管理器
• 已收集授权同意：每位被代行用户完成个人授权同意 URL 流程，或通过 DocuSign Admin 完成管理员授权同意
• demo 环境与生产环境分别完成授权同意
• iss（integration key）、sub（用户 ID）、aud（按环境区分）已接入 JWT 构建逻辑
• token 请求指向正确端点：demo 用 account-d.docusign.com，生产用 account.docusign.com
• /oauth/userinfo 的结果（account_id、base_uri）已缓存，以遵守每小时上限
• 每小时通过构建新 JWT 刷新 access token；不指望 refresh token
• 401 处理逻辑会用新 token 重试，而不是让交易失败
• 密钥轮换计划遵守五对密钥对上限：先加新密钥、切换、再移除旧密钥

面向亚太工作流的更简单 API 路径：Nota Sign

认证管道工程往往是亚太扩张计划撞上的第一堵现实之墙：一个能顺畅处理以美国为中心的工作流的平台，可能在区域身份与鉴证要求上栽跟头。Nota Sign 是法大大（FaDaDa）的全球化电子签名平台，天生为亚太而建：在香港原生支持 iAM Smart，在新加坡集成 Singpass，并提供 SES、AES、QES 签名等级，满足需要 eIDAS 式鉴证强度的工作流。

如果你仍在筛选平台，我们的开发者电子签名 REST API 横向对比和中国电子签名 REST API 实操指南覆盖了主要候选选项。如需围绕你的目标区域和鉴证等级规划集成方案，欢迎通过联系页面联系 Nota Sign 团队。