# 鉴权

> 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 归属到账号,多个项目建议各建一把,便于隔离与回收

## 安全实践

<Callout type="warn" title="不要在客户端暴露 Key">
浏览器、移动端 App、桌面客户端里都不要硬编码 Key —— 任何拿到它的人都能消耗你的余额。
需要前端直连时,由你的后端签发短期凭证或代理转发。
</Callout>

- 用环境变量或密钥管理服务注入,例如 `TOKROUTER_API_KEY`
- 不同环境(开发 / 预发 / 生产)用不同的 Key
- 怀疑泄露时立刻在控制台删除该令牌并重建 —— 删除即时生效
- 提交前用 secret 扫描拦住 `sk-` 开头的字符串

```bash
# .env.local(不要提交)
TOKROUTER_API_KEY=sk-xxxxxxxx
```

## 鉴权失败

| 现象 | 常见原因 |
| --- | --- |
| `401` | 缺少 `Bearer ` 前缀;Key 已删除、过期或被禁用;把账号密码当成了 Key |
| `403` | Key 所属分组没有该模型的权限 |
| `429` | 触发了速率限制或额度上限,见[计费与额度](/zh/billing/) |

具体的错误响应体字段见 [API 参考](/zh/api-reference/)。