跳轉到主要內容
一張長壽的憑證是一份悄悄增長的負債：代理被 除役、示範結束、承包商離開——但金鑰一直 運作，直到有人想起撤銷它。一把到期 API 金鑰翻轉 了那個預設值。你在鑄造金鑰時設定一個結束日期，而 OrcaRouter 會在那個日期過去的當下停止授權它——沒有需要記得的清理 任務，沒有「外洩但仍存活」的窗口。 到期是權杖物件上的一個欄位： expired_time。本頁是那一個控制的聚焦指南。要了解 同一畫面上的花費上限那一面，參見 配額上限與到期。

​
1. 為何要設定一把到期 API 金鑰

一把有時限金鑰的重點，是讓安全的結果成為預設的 那一個。幾個它能帶來回報的情況：

短暫代理

一個排程工作或短命代理會得到一把隨部署生命週期 一起消亡的金鑰。一個被遺忘的 cron 任務無法在數月 後仍持續花費。

示範與試用

遞給一位潛在客戶一把在評估期間有效、然後自行 熄滅的金鑰——無需後續撤銷。

承包商與供應商

把一張憑證的範圍限定到合作期。當合約結束時， 金鑰也隨之結束。

事故範圍限定的存取

在一次事故期間授予一把狹窄、短命的金鑰，使提升的 存取無法比事故本身存活得更久。
到期自然地與最小自主金鑰的其餘部分配對——一份模型 允許清單、一份 IP 允許清單，以及一個花費上限。每一項界定一個不同的 軸；它們合在一起讓一把被入侵金鑰的波及範圍維持微小。參見 最小自主檢查清單。

​
2. expired_time 欄位

一把金鑰的到期存在於權杖物件上的 單一欄位中：
欄位型別含義
expired_timeUnix 時間戳記（秒）金鑰停止授權的絕對瞬間。-1 意味著永不到期。
有兩件事要記住：
  • expired_time 是絕對的，而非一段持續時間。你設定金鑰 消亡的那個瞬間，而非「從現在起 30 天」——主控台日期選擇器會為你 計算時間戳記。
  • 一把新金鑰的預設值是 -1（永不）。一把金鑰只有在你 給它一個真實時間戳記時才會到期；把這個欄位原封不動地留著就會 鑄造一把不到期的金鑰。
一把不到期的金鑰（expired_time = -1）只有對一張你 主動輪替的憑證才是正確選擇。如果你能指出一把金鑰應該停止 運作的日期——而對代理、示範與承包商而言你通常可以——就設定它。 一把無人看管的 -1 金鑰最可能比它的用途存活得更久。

​
3. 在主控台中設定一個到期

設定一個到期是你的工作階段 / 存取權杖上的一個主控台動作—— 而非你在中繼呼叫上傳遞的東西。建立或編輯一把金鑰需要 Developer 角色或以上。
  1. 開啟 Keys（/console/token）並建立一把新金鑰，或編輯一把 現有的金鑰。
  2. 在到期欄位中，挑選金鑰應停止運作的日期與時間。 把它留白（或設為永不）以保持金鑰永久。
  3. 儲存。變更立即生效——無需重新部署、無需修改代理 程式碼。
編輯一把現有金鑰上的到期是即時的：延長一把即將 失效的金鑰，或把它的到期往前拉以更早讓它退役，新的 期限會在下一個請求上套用。
只有 /v1/* 中繼呼叫攜帶 sk-orca-… 金鑰。你在此設定的到期 治理那把中繼金鑰，但你是從主控台 工作階段設定它的，絕不透過把中繼金鑰送到一個管理路由。

​
4. 一把到期金鑰會做什麼

當一把金鑰在它的 expired_time 過去之後被出示時，閘道會 在驗證層拒絕它——請求從不抵達模型，所以它 不耗費任何配額。金鑰的狀態移動到 Expired，這是一把金鑰可達成的 自動終止狀態之一：
狀態如何達成
Enabled作用中；請求獲得授權。
Disabled你暫停了它；可逆。
Expired已過其 expired_time——自動達成。
Exhausted超出其配額 / 花費上限——自動達成。
Expired 在「金鑰不會再自行授權」的意義上是終止的。如果你 需要它回來，編輯金鑰把 expired_time 推到 未來（Developer+），它就會在下一個請求上回到 Enabled—— 金鑰、它的限制，以及它的政策附掛全都被保留。要徹底讓一把 金鑰退役，改為撤銷它。
到期 vs. 停用 vs. 撤銷。 到期是排程的關閉開關—— 你在最前面決定期限然後走開。 停用 是針對事故的手動、可逆的暫停。 撤銷（刪除）是 永久的。每當你已經知道一張憑證何時應該停止重要時，就 伸手取用到期。

​
5. 一個實作範例：一把兩週的示範金鑰

假設你正給一位潛在客戶一把用於 14 天評估的金鑰。你想讓它 呼叫一個便宜模型、花費不超過一個固定預算，並在試用 結束時熄滅——全部都不需要一個撤銷它的日曆提醒。 在 New key 對話框中，設定：
  • model_limits：["openai/gpt-4o-mini"]——示範無法伸手去拿一個 更貴的模型。
  • credit_limit_usd：一個固定的試用預算——一個失控的迴圈無法超出 它。
  • expired_time：14 天窗口的結束——金鑰在試用結束時 自行停止授權。
期限之後，這把金鑰上的任何進一步請求都會被拒絕且不花費 任何配額，而金鑰在清單中顯示為 Expired。沒有東西需要你 清理；該憑證讓它自己退役了。 
# Before expiry — authorized
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o-mini", "messages": [{"role":"user","content":"ping"}]}'

# After expiry — the same call is rejected at the auth layer,
# the model is never invoked, and no quota is consumed.

​
6. 誰能做什麼

到期受與一把金鑰生命週期其餘部分相同的角色閘控管， 範圍限定到你的作用中工作區：
動作最低角色
檢視一把金鑰的到期Viewer
設定或變更 expired_time（建立 / 編輯一把金鑰）Developer
重新顯示一把一般金鑰的明文Developer
讀取一把閘道範圍限定（is_firewall_gateway）金鑰的明文Admin
要了解完整的生命週期——建立、停用、撤銷——以及與到期配對的 輪替模式，參見 管理金鑰。

​
7. 下一步

配額上限與到期

到期的花費上限手足——除了用時間，也用美元界定一把 金鑰。

金鑰輪替

讓一把不到期金鑰不至於永遠存活的零停機交接。

權杖物件

一把金鑰所攜帶的每個欄位，包括 expired_time，以及各自 所限制的內容。

最小自主檢查清單

把到期與模型限制、IP 允許清單，以及花費上限結合，以得到一把 最小波及範圍的金鑰。
一把知道何時該停止的金鑰，就少了一張你必須記得 退役的憑證。每當你能指出日期時，就設定 expired_time——並讓 閘道為你做清理。