跳转到主要内容
一份长寿命的凭据是一项静悄悄增长的负债：智能体被退役、演示 结束、承包商离开——但密钥一直工作，直到有人想起来去吊销它。 一个到期 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. 在 expiry 字段中，挑选密钥应当停止工作的日期和时间。 留空（或设为永不）以保持密钥永久。
  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。你没有任何需要清理的东西； 凭据退役了它自己。 
# 到期之前 —— 被授权
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"}]}'

# 到期之后 —— 同样的调用在认证层被拒绝，
# 模型从未被调用，且不消耗配额。

​
6. 谁能做什么

到期由与密钥生命周期其余部分相同的角色门控所治理，限定到你的 活跃工作区：
操作最低角色
查看一个密钥的到期Viewer
设置或更改 expired_time（创建 / 编辑一个密钥）Developer
重新揭示一个普通密钥的明文Developer
读取一个网关限定（is_firewall_gateway）密钥的明文Admin
关于完整的生命周期——创建、禁用、吊销——以及与到期配对的 轮换模式，参见 管理密钥。

​
7. 下一步

配额上限与到期

到期的花费上限同胞——用美元和时间一起限定一个密钥。

密钥轮换

使一个不到期的密钥不至于永远存活的零停机交接。

令牌对象

一个密钥携带的每个字段，包括 expired_time，以及每一个 约束什么。

最小权限检查清单

把到期与模型限制、IP 允许列表和花费上限结合，得到一个 最小影响半径的密钥。
一个知道何时停止的密钥是你少一个需要记得退役的凭据。每当你 能说出那个日期时，就设置 expired_time——让网关替你做清理。