跳转到主要内容
每份长寿命凭据都应当按计划被替换，并在任何暴露迹象时立即替换。 安全地轮换 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）之下，而非中继密钥。假设你正在替换一个定时汇总器 智能体的密钥。创建继任者，使用相同的范围： 
# 控制台会话令牌 —— 不是 sk-orca-… 中继密钥
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）显示无流量时，先禁用再删除它： 
# 先暂停（可逆）—— 把旧密钥的状态设为 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}'

# 一旦你确定没有东西依赖它 —— 彻底吊销
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. 在你切断之前审查泄露密钥做了什么：按那个密钥（令牌）过滤请求 日志，以限定影响半径。
完整的事故运行手册见于 泄露密钥响应。
一个短的 expired_time 是轮换保险：一个 到期密钥 即使在你忘了手动轮换时 也会退役它自己，限定任何单个凭据可能被滥用的时长。

​
6. 下一步

管理密钥

这些步骤所基于的创建 / 禁用 / 吊销生命周期。

绑定策略到密钥

把相同的防护栏和防火墙策略带到继任者上。

到期密钥

设置一个到期，使密钥按一个截止时间轮换它们自己。

泄露密钥响应

一份凭据暴露时的紧急路径。
轮换不过是有纪律的重叠：一个在前任停止之前就工作的继任者。让每个 密钥保持狭窄范围，交接就保持平淡无奇——这正是你想从一次凭据 轮换中得到的。