鉴权
TokRouter 用 sk- 开头的 API Key 鉴权;本文说明两种鉴权头、Key 的作用域与轮换实践。
所有请求都要带 API Key。Key 在控制台「令牌」页创建,形如 sk-xxxxxxxx。
两种鉴权头
| 入站协议 | 头 | 示例 |
|---|---|---|
OpenAI(/v1/chat/completions、/v1/responses、/v1/models) | Authorization | Authorization: Bearer sk-… |
Anthropic(/v1/messages) | x-api-key | x-api-key: sk-… |
Gemini(/v1beta/*) | x-goog-api-key | x-goog-api-key: sk-… |
网关对两种头都接受,以你所用 SDK 的默认值为准,不要同时传。
Key 的作用域
- 一把 Key 覆盖所有模型与所有协议 —— 不需要按厂商分别申请
- Key 可以设额度上限和过期时间;超出上限或被禁用后,请求返回鉴权错误
- 用量与扣费按 Key 归属到账号,多个项目建议各建一把,便于隔离与回收
安全实践
不要在客户端暴露 Key
浏览器、移动端 App、桌面客户端里都不要硬编码 Key —— 任何拿到它的人都能消耗你的余额。 需要前端直连时,由你的后端签发短期凭证或代理转发。
- 用环境变量或密钥管理服务注入,例如
TOKROUTER_API_KEY - 不同环境(开发 / 预发 / 生产)用不同的 Key
- 怀疑泄露时立刻在控制台删除该令牌并重建 —— 删除即时生效
- 提交前用 secret 扫描拦住
sk-开头的字符串
# .env.local(不要提交)
TOKROUTER_API_KEY=sk-xxxxxxxx鉴权失败
| 现象 | 常见原因 |
|---|---|
401 | 缺少 Bearer 前缀;Key 已删除、过期或被禁用;把账号密码当成了 Key |
403 | Key 所属分组没有该模型的权限 |
429 | 触发了速率限制或额度上限,见计费与额度 |
具体的错误响应体字段见 API 参考。