认证
所有 /v1/* 请求都需要一个 akrouter API Key。三套协议放 key 的位置不同 —— 这是接入时最常见的一处坑。
创建 API Key
控制台 令牌管理 → 新建。Key 形如 ak-xxxxxxxxxxxxxxxxxxxxxxxx。
明文只出现一次
创建成功后完整 key 只显示这一次。之后列表里只保留后 4 位，服务端也不存明文 —— 丢了只能吊销重建。
每个 Key 可以单独配置：
- 允许调用的模型白名单
- 速率限制
- 价格上限与路由策略（见 路由策略）
Key 级策略与账号级策略合并时，收紧型字段取更严的一方： 账号级设了「只用认证商户」，某个 Key 没设，结果仍然是「只用认证商户」。 只有排序偏好这类放宽型字段才由 Key 直接覆盖。
三套协议的放置位置
我们按客户端的原生习惯收 key，不强行统一 —— 统一了反而要求你改客户端， 那就违背了「改 base_url 就能用」。
| 协议 / 入口 | 请求头 | 示例 |
|---|---|---|
| anthropic · /v1/messages | x-api-key | x-api-key: ak-xxxxxxxxxxxxxxxxxxxxxxxx |
| openai_responses · /v1/responses | Authorization | Authorization: Bearer ak-xxxxxxxxxxxxxxxxxxxxxxxx |
| openai_chat · /v1/chat/completions | Authorization | Authorization: Bearer ak-xxxxxxxxxxxxxxxxxxxxxxxx |
Claude Code 用的环境变量是 ANTHROPIC_AUTH_TOKEN，它会自己转成x-api-key 头；Codex 与 OpenAI SDK 用 OPENAI_API_KEY， 转成 Authorization: Bearer。两套协议同时收 Authorization 也可以， 我们两个头都认。
shell
# anthropic curl https://api.akrouter.com/v1/messages -H "x-api-key: ak-xxxxxxxxxxxxxxxxxxxxxxxx" # openai_chat / openai_responses curl https://api.akrouter.com/v1/chat/completions -H "authorization: Bearer ak-xxxxxxxxxxxxxxxxxxxxxxxx"
你的 key 不会被转发给上游
转发前我们会剥离下游凭据，替换成渠道账号自己的凭据。 你的 Authorization / x-api-key 不会出现在发往任何商户的请求里。
除凭据外的请求头默认放行，尤其是 anthropic-beta、openai-beta、anthropic-version —— 这些是特性开关，剥掉会让功能静默失效。 被剥的只有 hop-by-hop 头、host、content-length、 以及边缘层注入的 cf-* / x-forwarded-*。
认证失败
| 状态码 | 含义 | 怎么办 |
|---|---|---|
| 401 | key 不存在、已吊销或格式错误 | 检查是否复制完整、是否用了已删除的 key |
| 402 | 余额不足 | 控制台钱包充值；余额是硬门槛，不会赊账 |
| 403 | 该 key 不允许调用这个模型 | 检查 key 的模型白名单 |
错误响应会按你的客户端协议的形状返回 —— 给 Claude Code 回 OpenAI 形状的错误，等于把错误信息丢掉。详见 错误码与重试语义。