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 階段：沒有文件的 cron 排程工作和被遺忘的 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 指南。不設按席位收費，小團隊擴展時無須為席位數焦慮；中端市場與企業買家可洽談定制方案。想從第一天起就規劃對輪換友好的憑證，與我們展開對話。
