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 API 的整體使用成本。

服務整合 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 團隊。