如何零停機輪換 UnifyPort API Key

要在服務不中斷的情況下輪換 UnifyPort API Key，不要先呼叫 rotate 端點。POST /v1/api-keys/{key_id}/rotate 成功後會即時令舊 Key 失效。安全次序是先建立第二把有效 Key，保存只顯示一次的新密鑰，部署到所有呼叫端，用 GET /v1/workspace 驗證，最後才把舊 Key 設為 inactive。

重點

• rotate 端點採即時切換，沒有舊 Key 寬限期。
• 零停機更換需要短時間保留兩把有效 Key，依次建立、部署、驗證及停用。
• 完整新密鑰只會在 data.api_key 回傳一次，之後不能再次讀取。
• Key 清單只提供 key_prefix、狀態等 metadata。
• 一般滾動部署應採「建立後停用」；需要即時撤銷舊憑證時才用 rotate。

為何直接 rotate 可能令正式環境中斷

Rotate API key 文件定義以下操作：

POST /v1/api-keys/{key_id}/rotate

它會建立新的 Key 記錄並只回傳一次新密鑰，同時即時令舊 Key 無效。若舊憑證可能已外洩，這種行為很重要；但若網頁程序、queue worker、排程工作或其他區域的 instance 仍使用舊值，請求便可能收到 401 invalid_api_key。

滾動部署本來就有新舊設定短暫並行的階段。即時撤銷舊憑證會移除這個重疊期，令原本健康的程式也出現認證錯誤。

NIST SP 800-53 的 authenticator management 控制包含更換或更新認證器的一般原則；實際操作仍要依產品合約安排。UnifyPort 可保留多條 API Key 記錄，而 rotate 會即時淘汰原有 Key。

零停機 API Key 輪換流程

1. 先盤點所有呼叫端

列出所有向 https://api.unifyport.ai 發送 X-Api-Key 的元件，包括公開 API、背景 worker、會發出回覆請求的 webhook 工作、排程、正式環境工具及健康檢查。

API Key 並不是 webhook 的 signing_secret。前者認證你向 UnifyPort REST API 發出的請求；後者用來驗證送到接收端的 webhook。關於後者，可參考 Webhook HMAC、重送防護及重試指南。

先用 List API keys 檢視記錄：

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

回應提供 id、name、key_prefix 及 status，不會顯示完整密鑰。

2. 建立第二把有效 Key

使用 Create API key，而不是 rotate：

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

成功的 201 回應會在 data.key 提供 metadata，並在 data.api_key 回傳一次完整新密鑰。應直接把它存入團隊認可的 secrets manager，不要輸出到部署 log、工單或聊天訊息。

若部署前遺失這個一次性值，請另建一把 Key，並停用未使用的記錄；不能由 prefix 還原完整密鑰。

3. 部署前先測試新 Key

用新密鑰進行唯讀認證檢查：

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

成功回應代表新 Key 可連到工作區，但不代表所有 instance 都已載入它。下一步是更新部署引用的 secret，逐批發布到每一類呼叫端，期間保持舊 Key 為 active。

變更紀錄可以寫部署版本、instance group 及負責人，但不要記錄任何密鑰值。

4. 驗證整個服務群組

停用舊 Key 前逐項確認：

• Web 及 API instance 已完成發布；
• queue consumer 已重新啟動或重新載入設定；
• 排程下次執行會讀取新密鑰；
• 訊息回覆或發送路徑可完成已認證請求；
• 沒有緊急 script 依賴複製到本機的舊值。

這一步應依據應用程式請求結果和部署狀態。UnifyPort Key 清單只顯示 metadata 和狀態，文件並未提供每把 Key 的最後使用時間，因此不要根據不存在的欄位推斷遷移已完成。

若團隊由控制台開始，可先閱讀控制台及 API Key 管理公告。本文補充的是正式系統所需的部署次序。

5. 停用舊 Key

確認所有呼叫端均使用新密鑰後，用新 Key 呼叫 Update API key status：

curl -X PATCH "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

文件支援 active 及 inactive。停用後，用舊密鑰進行一次受控唯讀請求，確認收到 401 invalid_api_key；不要用真實業務工作作測試。

最後，從部署設定、本機環境檔、CI variable 及臨時遷移材料刪除舊值。操作紀錄只保留 Key ID、名稱、狀態、負責人和切換時間等非敏感資料。

何時應使用即時 rotate

只有當「舊憑證必須立即失效」本身就是目標時，才使用 POST /v1/api-keys/{key_id}/rotate。常見情況包括懷疑憑證外洩，或所有呼叫端都能在維護時段同步切換。

這時的次序是：

1. 暫停或隔離仍持有舊 Key 的呼叫端；
2. 從受控操作路徑呼叫 rotate；
3. 只擷取一次 data.api_key；
4. 更新所有 secret consumer；
5. 恢復流量並驗證認證。

這個方案優先撤銷速度，而非持續可用性。若懷疑外洩，不應為保持流量而延長兩把 Key 並行的時間，應依照安全事件流程處理。

限制與取捨

短暫雙 Key 階段代表兩份有效憑證都可以存取工作區。應盡量縮短時間，並限制可接觸密鑰的人員和系統。UnifyPort 文件指出 X-Api-Key 會解析到一個工作區並授予其中的存取能力，因此這並非按 endpoint 劃分權限的遷移。

本流程亦不會輪換 webhook signing_secret、平台登入資料或匯入 session。不同 secret 有不同使用端及故障模式，應分開變更和測試。

FAQ

UnifyPort API Key 輪換有寬限期嗎？

文件中的 rotate 端點沒有寬限期，成功後舊 Key 即時失效。需要重疊時間時，應先建立第二把 Key。

之後可以再次讀取新 API Key 嗎？

不可以。完整值只在 data.api_key 回傳一次，之後清單只顯示 prefix、狀態等 metadata。

如何安全測試新 Key？

用新的 X-Api-Key 呼叫 GET /v1/workspace，再確認每類已部署呼叫端都載入新密鑰，然後才停用舊記錄。

應用 rotate，還是建立後停用？

一般滾動部署使用建立後停用；需要立即撤銷舊憑證，而且已隔離所有舊呼叫端時才用 rotate。

API Key 和 signing_secret 相同嗎？

不同。X-Api-Key 認證 REST API 請求；signing_secret 用於驗證 webhook 的 HMAC-SHA256 簽署。

下一步

開啟 Create API key 參考，建立並行正式憑證，在更改舊 Key 狀態前完成以上五個檢查點。

資料來源

核對日期：2026 年 8 月 17 日。

• UnifyPort：Create API key
• UnifyPort：List API keys
• UnifyPort：Update API key status
• UnifyPort：Rotate API key
• NIST SP 800-53 Revision 5