用 OpenRouter 管理型 API key 自动化管密钥：轮换与作用域

依据 OpenRouter 官方文档 2026-08-18 的公开内容整理。该平台迭代频繁，文中涉及的端点、字段与参数语义请以官方文档最新内容为准。

一、这件事卡在哪

如果你的服务只有一个进程、一把 key 写在 .env 里，那轮换密钥是个手工活：登录、建新 key、改环境变量、重启、删旧 key。麻烦，但能忍。

真正难受的是另外两种处境。一种是你在做多租户的东西——每个客户实例要一把自己的 key，好把用量和风险隔开，这时候「手工建 key」直接就不成立了。另一种是合规要求你定期轮换凭据，季度一次或者更密，而你有一堆服务、几条 CI/CD 流水线都在用同一把 key，手工换一轮下来总有一处漏网，漏的那处就是半夜的告警。

OpenRouter 对这两种处境给的答案是一组管理端点：/api/v1/keys。官方文档《Management API Keys》页把它的定位写成「programmatically manage your API keys」，用途列了三类——为每个客户实例自动创建 key（SaaS 场景）、为安全合规做定期轮换、监控用量并自动停用超限的 key。

要用这组端点，你需要的不是平时那把 key，而是另一种 key。这是本文的第一个落点。

二、前置条件：管理 key 和普通 key 的权限差异

这一步别跳。两种 key 的作用域是互斥的，文档里写得很直白：

Management keys cannot be used to make API calls to OpenRouter’s completion endpoints - they are exclusively for administrative operations.

翻成人话：管理 key 只能做管理操作，拿它去调补全端点是不行的。反过来，/api/v1/keys 下的所有端点，文档写明「require a Management API key in the Authorization header」——也就是说，你平时发推理请求的那把 key 也管不了这组端点。

两句合起来，得到的就是一条互斥的作用域：两把 key 的能力集不重叠。文档并没有解释为什么这么切，我们也不替它补理由——这里只陈述边界本身。要注意的是，「作用域」在这里只有粗粒度的这一刀。管理 key 内部是否还能再细分（比如只读、只允许操作某几把 key、限定来源 IP），官方文档这两页没有说明这一点，我们也没有在别处检索到对应描述。所以实践上你只能按「这把管理 key 等于账户内全部 key 的完全控制权」来对待它。

创建管理 key 的路径，文档写成三步：进入 openrouter.ai/settings/management-keys 这个页面，点 “Create New Key”，走完创建流程。文档原文就这么多——我们没有截图，也不描述这个页面长什么样。

调用侧的前置条件：

• TypeScript 走官方 SDK，包名是 @openrouter/sdk，构造 new OpenRouter({ apiKey: ... }) 时传的是管理 key
• Python 侧官方示例直接用 requests 打 HTTP，没有走 SDK
• 也可以纯 fetch，文档给了第三份等价示例
• SDK 与 Python 的最低版本要求，文档没有说明这一点

顺带说一句本地存放。把管理 key 放进环境变量是通用做法（这一段不是 OpenRouter 官方文档的内容，只是常规运维习惯，变量名也由你自己定，官方文档没有约定管理 key 的环境变量名）。以 OPENROUTER_MANAGEMENT_KEY 这个自拟的名字为例：Linux / macOS 侧是 export OPENROUTER_MANAGEMENT_KEY="<YOUR_API_KEY>"；Windows PowerShell 侧是 $env:OPENROUTER_MANAGEMENT_KEY="<YOUR_API_KEY>"，只在当前会话有效，要持久化得走系统的环境变量设置。别把它和推理用的那把混在同一个变量名里，两者作用域不同，混了迟早出事。

三、/api/v1/keys 上有哪几个动作

文档给出的动作是五个，SDK 侧和 REST 侧一一对应：

动作	REST	SDK 方法	说明
列出	GET /api/v1/keys	apiKeys.list()	支持 offset 查询参数翻页
创建	POST /api/v1/keys/	apiKeys.create()	参数 name，可选额度上限
查单个	GET /api/v1/keys/{hash}	apiKeys.get(keyHash)	用 hash 定位，不是用 key 本身
更新	PATCH /api/v1/keys/{hash}	apiKeys.update(keyHash, {...})	改名、停用、额度重置等
删除	DELETE /api/v1/keys/{hash}	apiKeys.delete(keyHash)	同样用 hash

有个坑值得先说：同一批参数，SDK 侧是驼峰、REST 侧是下划线。文档的 TypeScript SDK 示例里写 includeByokInLimit、limitReset，Python 与 fetch 示例里写的是 include_byok_in_limit、limit_reset。两边指的是同一件事。至于 REST 端点会不会也接受驼峰写法、传错写法时是被忽略还是报错，文档没有说明这一点——所以照 SDK 的写法去拼 JSON body 之前，先回 API 参考页对一遍字段名，别想当然。

更新时可用的参数，文档示例里出现的有这几个：name（改显示名）、disabled（布尔，停用这把 key）、include_byok_in_limit（控制 BYOK 用量算不算进额度）、limit_reset（示例值是 'daily'，文档注释说明是「每天 UTC 零点重置额度」）。limit_reset 的完整取值枚举，这两页文档没有列出来；只在用途那一节提到过存在 daily / weekly / monthly 三种粒度的额度重置，以及响应里对应有按日 / 周 / 月的用量字段。要拿准枚举值，去查 API 参考页。

响应形态是 JSON，列表放在 data 数组里，每个对象文档列出的字段包括：created_at、updated_at、hash、label、name、disabled、limit、limit_remaining、limit_reset、include_byok_in_limit，加上 usage、usage_daily、usage_weekly、usage_monthly 以及对应的四个 byok_usage*。注意文档示例里的 label 是掩码形式的展示串，不是完整 key。

完整 key 字符串只在创建那一次的响应里出现——文档原话是「When creating a new key, the response will include the key string itself」。别的地方拿不到。这条决定了下面轮换流程的所有取舍。

四、零停机轮换：三步各自在改什么

文档《API Key Rotation》页把策略压缩成一句：创建新 key、把应用切到新 key、等所有系统迁完再删旧 key。关键在于文档明确写了过渡期的行为——「Both keys remain valid during this transition period」，两把 key 同时有效，所以可以灰度推，不用停服。

第一步：创建新 key

import requests

MANAGEMENT_API_KEY = "<YOUR_API_KEY>"
BASE_URL = "https://openrouter.ai/api/v1/keys"

response = requests.post(
    f"{BASE_URL}/",
    headers={
        "Authorization": f"Bearer {MANAGEMENT_API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Production Key - Rotated 2025-01",
        "limit": <你定的额度上限>
    }
)

data = response.json()
print(f"New key created: {data['data']['key']}")
print(f"Key hash: {data['data']['hash']}")

结构与字段名照抄官方 Python 示例，只有两处替换：密钥换成占位符，limit 的具体数值换成占位（原文给的是一个示例数字，本站不写额度数值，这个字段官方标注为可选的额度上限）。

这里有个必须当场做的动作：把响应里的 hash 存下来。文档专门用 Tip 提示了这一点——删除旧 key 时要用 hash，而不是 key 本身。如果你只把新 key 写进了密钥管理器、没留 hash，将来想删这把 key 就得先去 list 里翻着找。

name 那个示例值也值得抄：官方在最佳实践里建议名字里带轮换日期或版本号，方便追溯。这不是装饰，是你三个月后回头看 list 输出时唯一能分辨新旧的东西。

第二步：把应用切过去

这一步文档没有给命令，只列了三类常见做法：改部署配置里的环境变量、在密钥管理器里轮换（文档点名举例 AWS Secrets Manager、HashiCorp Vault），或者更新 CI/CD 流水线变量。具体怎么做取决于你的基础设施，文档不管这一段。

第三步：删掉旧 key

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<YOUR_API_KEY>',
});

const oldKeyHash = 'hash-of-old-key';
await openRouter.apiKeys.delete(oldKeyHash);

以上代码按官方文档中的示例与参数语义整理，我们未经实测，以官方文档与 API 参考的实际说明为准。

文档在这一步之前挂了一条 Note：删旧 key 之前一定要先确认新 key 在生产环境已经工作，避免误伤。这条读起来像废话，但它决定了第五节的验证动作不能省。

一个把两处文档放在一起才看得出来的用法：轮换流程写的是直接 delete，而更新接口里有个 disabled 参数，用途那一节也提到「自动停用超限的 key」。这两处合起来，一个可以考虑的做法是：删除之前先把旧 key disabled: true 停用一段时间，观察一阵再删，而 disabled 是可以改回去的，比删除多一层回退余地。但要把话说清楚：文档只把 disabled 描述成「停用这把 key」，停用之后再拿这把 key 发请求会得到什么结果，文档没有说明这一点；文档也没有把这一步写进轮换流程。这是把两页里的两个事实拼起来得到的读法，不是官方推荐步骤，真要这么做请自己在非生产环境先验证。

五、边界：文档没说的部分

这些地方我们检索不到依据，照实标出来，别自己脑补：

• 管理 key 自身怎么轮换，文档只写了在设置页创建，没有说明能不能用 API 程序化地创建或轮换管理 key
• 管理 key 的细粒度权限（只读、限定操作对象、IP 白名单）没有说明
• 删除 key 之后的生效时机——在途请求怎么处理、是否有传播延迟，没有说明
• 拿普通推理 key 去调 /api/v1/keys 会返回什么错误，没有说明；只写了这组端点要求管理 key
• list 一页返回多少条，本文不写具体数字。文档示例里的翻页方式是在 URL 上挂 ?offset= 查询参数，示例里那个偏移量取值只是示例，页大小以 API 参考为准
• 这两页文档里没有出现 beta / preview / experimental / deprecated 标记，所以本文也不给这些功能贴任何状态标签——但这只代表这两页没标，不代表将来不会变

还有一处是能力而不是缺口，值得单独说：如果你用的是 BYOK（把自己的 provider key 托管在 OpenRouter），文档写明 provider key 是绑在账户上、不是绑在单把 OpenRouter key 上，管理入口在 openrouter.ai/settings/integrations。这意味着你轮换 OpenRouter key 的时候完全不用动 provider 那边的凭据——对于有硬性轮换周期的团队，这一条省掉的是跨多家 provider 同时轮换的那份麻烦。

六、怎么验证配对了

按依赖强度从弱到强排：

1. 看创建响应。data.key 和 data.hash 都拿到了，说明管理 key 的权限没问题。如果这一步就失败，第一个该排除的可能是把推理 key 当成管理 key 在用——两者作用域互斥，这是文档写明的；至于这种情况下具体会返回什么错误，文档没有说明，别照着猜出来的错误码写判断逻辑。
2. 调 list 或 get 复核。用第一步存下来的 hash 调 GET /api/v1/keys/{hash}，确认 name 与你创建时传的一致、disabled 是 false。
3. 看用量字段迁移。响应里那组 usage / usage_daily / usage_weekly / usage_monthly 字段，是判断流量是否真的换到新 key 上的直接依据：新 key 的用量开始动、旧 key 不再增长，才算迁完。这里只看趋势，不需要关心具体数值。
4. 看 Activity 页。文档最佳实践里明确建议，删旧 key 之前去 openrouter.ai/activity 核实流量已经迁移过去。

文档在最佳实践里还提了两条容易被跳过的：先在非生产环境跑一遍轮换流程再上生产；把轮换节奏文档化并固定下来（原文举的例子是按季度）。这两条没有技术含量，但轮换出事故基本都出在「这次赶时间，直接在生产上换」。

---

本文依据 OpenRouter 官方文档（openrouter.ai/docs）于 2026-08-18 的公开内容整理。 该平台闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观与运行表现的任何描述。 该平台的供应商、模型与路由策略随时变动，文中不列具体供应商名单与模型清单； 价格、额度与限流的具体数值请以官方定价页与用量说明为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。