跳轉到主要內容
每張長壽的憑證都應該按排程被替換，並在任何暴露的 跡象上立即替換。安全地輪替 API 金鑰憑證的方式， 絕不是就地變動一把存活金鑰——而是鑄造一把全新的、 把流量移到它上面，並在沒有任何東西依賴舊的那把時讓它退役。 依那個順序做，就永遠不會有一個沒有可用金鑰的瞬間。 本頁是逐步手冊。要了解更廣的金鑰生命週期 （建立 / 停用 / 刪除），參見管理金鑰； 要了解一把金鑰所攜帶的每個欄位，參見權杖物件。
這裡所有的主控台動作都位於 Keys 畫面（/console/token）中 且在你的工作階段 / 存取權杖上執行——而非中繼金鑰。建立、 編輯、停用或刪除一把金鑰需要 Developer 角色或 以上。只有 /v1/* 推論呼叫使用 sk-orca-… 中繼金鑰。

​
1. 為何輪替，以及為何絕不就地

OrcaRouter 上的一把金鑰是一個不可變的身份，而非僅是一串字串——它 攜帶它自己的模型允許清單、IP 允許清單、花費上限、到期，以及 政策附掛。你無法變更一把現有金鑰的 密鑰材料；憑證與限制是在建立時一起發行的。 所以「輪替」意味著發行一個後繼者並遷移到它上面。在以下時候做：
  • 對任何生產憑證按固定節奏（每季是一個常見的 基準）；
  • 一把金鑰被懷疑外洩的當下——不過對於一個已確認的外洩，先 切斷它再輪替（參見外洩金鑰回應）；
  • 每當金鑰的擁有者（一名員工、一個供應商整合、一個 已除役的代理）改變時。
明文（sk-orca-…）在建立時顯示一次——那時就複製它。 之後主控台只顯示一個像 orca-7Bf****wxyz 的遮罩形式。 一個 Developer+ 可以日後重新顯示一把一般金鑰的明文，但一把 閘道範圍限定金鑰（is_firewall_gateway）需要 Admin 才能再次 讀取它的明文——所以把閘道金鑰的第一次顯示當作你唯一 可靠的複製。

​
2. 輪替 API 金鑰的順序

整個重點是一個乾淨的重疊：新金鑰在舊的那把停止之前就 運作。四個步驟。
1

建立後繼金鑰

鑄造一把帶有與你要替換的那把相同範圍的新金鑰—— 相同的 model_limits、allow_ips、credit_limit_usd、expired_time， 以及相同的 guardrail_id / firewall_policy_id。立即複製明文。 輪替也是收緊範圍的理想時機：丟掉一個代理不再使用的 模型，或收窄 IP 允許清單。
2

遷移流量

把新的 sk-orca-… 部署到每個呼叫者——設定、密鑰管理器、 CI 變數、代理執行期。用你出貨任何密鑰變更的同樣方式 推出它。此時兩把金鑰都存活，所以部署可以 錯開而不造成中斷。
3

驗證新金鑰正在承載負載

在你動到舊的那把之前，確認後繼者實際上正在服務 流量。觀察新金鑰的 used_quota 攀升而舊金鑰的 趨平——每把金鑰各自的使用就是你的切換信號。
4

讓舊金鑰退役

一旦舊金鑰顯示沒有流量，先停用它（可逆） 並留意零星殘留，然後徹底刪除它。停用是 暫停；刪除是不歸路。
在每把金鑰上設定一個 environment 標籤—— 跨舊金鑰與新金鑰重複使用它，或遞增它（prod → prod-2026q2）—— 使後繼者與前任在重疊窗口期間兩者都存活時被清楚地 區分標記。

​
3. 一次具體的輪替，經由 REST

下方一切都是一個主控台動作——這些管理路由在 你的工作階段（UserAuth）下執行，而非中繼金鑰。假設你正替換 一個排程摘要器代理的金鑰。用相同範圍建立後繼者： 
# Console session token — NOT an sk-orca-… relay key
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
回應傳回明文一次（"data": "sk-orca-…"）。複製 它、把它部署到摘要器，並在繼續之前確認新金鑰正在 服務。 當舊金鑰（id 481）顯示沒有流量時，先停用再刪除它： 
# Pause first (reversible) — set the old key's status to Disabled (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Once you're sure nothing depends on it — revoke for good
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
一把金鑰的狀態是 Enabled（1）、Disabled（2）、Expired（3），或 Exhausted（4）之一。停用會把它設為 Disabled；金鑰 發出的每個請求接著都被拒絕，同時它的設定、附掛與歷史保持 完整。刪除是永久的——憑證再也無法授權一個 請求，而一把已刪除的金鑰不可復原。
你可以在沒有 API 的情況下做這一切——Keys 畫面有 New key、一個每把金鑰各自的 Disabled 切換，以及 Delete（單個或批次）。 上方的 REST 形式是用於編寫排程輪替腳本的。

​
4. 輪替政策綁定金鑰與閘道金鑰

一把金鑰的防護欄與防火牆附掛 存在於金鑰上，所以後繼者必須攜帶相同的 guardrail_id 與 firewall_policy_id 才能強制執行相同的姿態。有兩件事要知道：
防護欄與防火牆政策是工作區範圍限定、跨金鑰 共享的命名資源。輪替一把金鑰不會動到政策本身； 你只是把一把全新金鑰重新指向既有的 guardrail_id / firewall_policy_id。政策不間斷地持續治理流量。
一把設定了 is_firewall_gateway 的金鑰驅動 防火牆閘道 路由（/api/v1/firewall/*）。鑄造一把，以及重新顯示其 明文，兩者都需要 Admin。因為你無法隨意重新讀取 它的密鑰，在建立時捕捉新閘道金鑰的明文並 在你切換之前把它存到你的密鑰管理器中。
別跨許多代理重用單一金鑰——無論是不是閘道金鑰——並靠 編輯限制來「輪替」。每個代理一把金鑰讓每次輪替維持隔離， 並讓波及範圍維持微小。參見 最小自主檢查清單。

​
5. 緊急輪替（懷疑外洩）

如果你認為一把金鑰被暴露，順序翻轉：先止血， 再遷移。
  1. 立刻停用可疑金鑰，使它在你調查時無法授權 任何東西——或如果外洩已確認就直接刪除它。
  2. 鑄造後繼者並如 §2 那樣推出它。
  3. 在你切斷外洩金鑰之前，檢視它做了什麼：按那把金鑰 （token）篩選請求日誌以界定波及範圍。
完整的事故執行手冊位於外洩金鑰回應。
一個短的 expired_time 是輪替保險：一把 到期金鑰即使你忘了手動輪替也會 讓它自己退役，界定任何單一憑證能被濫用多久。

​
6. 下一步

管理金鑰

這些步驟所建立於其上的建立 / 停用 / 撤銷生命週期。

綁定政策到金鑰

把相同的防護欄與防火牆政策帶到後繼者上。

到期金鑰

設定一個到期，使金鑰在一個期限上輪替它們自己。

外洩金鑰回應

當一張憑證暴露時的緊急路徑。
輪替只是有紀律的重疊：一個在前任停止之前就運作的 後繼者。讓每把金鑰維持狹窄範圍限定，交接就會保持 無趣——而那正是你想從一次憑證輪替中得到的。