如何零停機輪替 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、狀態等中繼資料。
• 一般滾動部署使用「建立後停用」；需要立即撤銷舊憑證時才使用 rotate。

為什麼直接 rotate 會中斷正式環境

Rotate API key 文件定義的操作是：

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

它會建立新的 Key 記錄並只回傳一次新密鑰，同時讓舊 Key 立即失效。若舊憑證可能外洩，這個行為很重要；但若網頁程序、佇列 worker、排程工作或不同區域的執行個體仍讀取舊值，就可能收到 401 invalid_api_key。

滾動部署原本就需要一段新舊設定並行的時間。原子式憑證切換會移除這段重疊，使健康的應用程式也發生驗證錯誤。

NIST SP 800-53 的驗證器管理控制涵蓋變更或更新驗證器的一般原則；實際順序仍必須配合產品契約。UnifyPort 支援多筆 API Key 記錄，而 rotate 會立即淘汰前一把 Key。

零停機 API Key 輪替操作手冊

1. 先盤點所有呼叫端

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

API Key 不等於 webhook 的 signing_secret。前者驗證你的 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 提供中繼資料，並在 data.api_key 回傳一次完整新密鑰。應直接存入團隊核准的密鑰管理系統，不要輸出到部署紀錄、工單或聊天訊息。

若部署前遺失這個一次性值，請再建立一把 Key，並停用未使用的記錄；不能由前綴推回完整值。

3. 部署前先證明新 Key 可用

使用新密鑰進行唯讀驗證：

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

成功回應代表新 Key 可解析到工作區，但尚不能證明所有執行個體都已載入。接著更新部署所引用的密鑰，逐批發布到每一類呼叫端，期間保持舊 Key 為 active。

變更紀錄可保存部署版本、執行個體群組與負責人，但不要保存任何密鑰值。

4. 驗證整個服務群組

停用舊 Key 前逐項確認：

• Web 與 API 執行個體已完成發布；
• 佇列消費者已重新啟動或重新載入設定；
• 排程下次執行時會取得新密鑰；
• 訊息回覆與傳送路徑可完成已驗證請求；
• 沒有緊急腳本依賴複製到本機的舊值。

請依據應用程式端的請求結果與部署狀態做判斷。UnifyPort 的 Key 清單只顯示中繼資料與狀態，文件未提供每把 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 變數與暫時遷移材料移除舊值。作業紀錄只保留 Key ID、名稱、狀態、負責人及切換時間等非敏感資訊。

何時該使用即時 rotate

只有在「舊憑證必須立刻失效」是主要需求時，才使用 POST /v1/api-keys/{key_id}/rotate，例如懷疑憑證外洩，或所有呼叫端可在維護時段同步切換。

此時流程是：

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

這個方案優先考慮撤銷速度，而不是連續可用性。若疑似外洩，不應為了保持流量而延長雙 Key 並行時間，請依安全事件流程處理。

限制與取捨

短暫的雙 Key 階段代表兩份有效憑證都能存取工作區。應盡量縮短時間，並限制可接觸密鑰的人員與系統。UnifyPort 文件說明 X-Api-Key 會解析到一個工作區並授予其中的存取能力，因此這不是每個端點各自設定權限的遷移。

本流程也不會輪替 webhook signing_secret、平台登入資料或匯入的工作階段。不同秘密有不同的使用端與故障模式，應分開變更與測試。

FAQ

UnifyPort API Key 輪替有寬限期嗎？

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

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

不可以。完整值只在 data.api_key 回傳一次，後續清單只顯示前綴與狀態等中繼資料。

如何安全測試新 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