OpenRouter Management API Keys 允许通过 /api/v1/keys 端点以编程方式管理 API Key，适用于 SaaS 应用（为每个客户实例创建独立 Key）、定期密钥轮换（安全合规）和用量监控（自动禁用超额 Key）三类场景。需先创建专用的 Management Key（只能用于管理操作，不能调用模型），然后通过 openRouter.apiKeys.list/create/get/update/delete 等方法操作。响应格式含 hash、limit、limit_remaining、limit_reset、usage 等字段，支持按日/周/月重置限额。

OpenRouter 提供 API Key 编程管理能力，适用于需要自动化创建、轮换或监控 API Key 的应用。

创建 Management API Key

1. 前往 Management API Keys 页面
2. 点击"Create New Key"完成创建

Management Key 只能用于管理操作（增删改查 API Key），不能用来调用 OpenRouter 的模型 endpoint。

使用场景

• SaaS 多租户 — 为每个客户实例自动创建独立的 API Key，隔离用量
• 定期轮换 — 按安全合规要求定时轮换，零停机
• 用量监控 — 设置用量上限，自动禁用超额 Key（支持按日/周/月重置）

使用示例

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

const openRouter = new OpenRouter({
  apiKey: 'your-management-key', // 使用 Management Key
});

// 列出最近 100 个 API Key
const keys = await openRouter.apiKeys.list();

// 分页（从第 101 个开始）
const keysPage2 = await openRouter.apiKeys.list({ offset: 100 });

// 创建新 Key
const newKey = await openRouter.apiKeys.create({
  name: 'Customer Instance Key',
  limit: 1000, // 可选：设置 credits 上限
});

// 获取指定 Key
const keyHash = '<YOUR_KEY_HASH>';
const key = await openRouter.apiKeys.get(keyHash);

// 更新 Key
const updatedKey = await openRouter.apiKeys.update(keyHash, {
  name: 'Updated Key Name',
  disabled: true,               // 禁用 Key
  includeByokInLimit: false,    // BYOK 用量是否计入 limit
  limitReset: 'daily',          // 每天 UTC 0 点重置 limit
});

// 删除 Key
await openRouter.apiKeys.delete(keyHash);

响应格式

{
  "data": [
    {
      "created_at": "2025-02-19T20:52:27.363244+00:00",
      "updated_at": "2025-02-19T21:24:11.708154+00:00",
      "hash": "<YOUR_KEY_HASH>",
      "label": "sk-or-v1-abc...123",
      "name": "Customer Key",
      "disabled": false,
      "limit": 10,
      "limit_remaining": 10,
      "limit_reset": null,
      "include_byok_in_limit": false,
      "usage": 0,
      "usage_daily": 0,
      "usage_weekly": 0,
      "usage_monthly": 0,
      "byok_usage": 0,
      "byok_usage_daily": 0,
      "byok_usage_weekly": 0,
      "byok_usage_monthly": 0
    }
  ]
}

关键字段说明：

字段	说明
hash	Key 的唯一标识符，用于 get/update/delete 操作
label	Key 的脱敏前缀（sk-or-v1-abc...123）
limit	Credits 用量上限（null 表示无限制）
limit_remaining	剩余可用 credits
limit_reset	重置周期：daily、weekly、monthly 或 null
usage / usage_daily 等	总用量及各周期用量统计
byok_usage	BYOK 请求的用量（独立统计）

创建新 Key 时，响应还会包含完整的 Key 字符串（只显示一次）。

常见问题

Q: Management Key 和普通 API Key 有什么区别？

A: Management Key 专用于管理操作（增删改查其他 API Key），不能调用模型 endpoint。普通 API Key 用于调用模型，不能管理其他 Key。两者是完全独立的凭证类型。

Q: limit_reset 和 limit 组合如何实现"每天最多消费 $X"？

A: 设置 limit（如 10 credits）和 limitReset: 'daily'，系统会在每天 UTC 0 点自动将 limit_remaining 重置为 limit 值，实现滚动限额。

Q: 如何实现零停机密钥轮换？

A: 推荐流程：① 用 Management API 创建新 Key → ② 更新应用配置指向新 Key → ③ 删除旧 Key。配合 BYOK 使用时，轮换 OpenRouter Key 不需要动 provider 凭证，进一步简化密钥管理。