鉴权与密钥
密钥的五个位置、优先级、轮换与停用,以及 /v1 与 /api 两个命名空间为什么不通用。
内容最后核对:2026-11-18
本页目录
一把密钥,五个位置
Authorization: Bearer <key> 是文档与示例里唯一给出的形式。另外四个位置也接受,取到的都是同一串明文、走同一次校验:
| 优先级 | 位置 | 常见来源 |
|---|---|---|
| 1 | Authorization: Bearer | OpenAI 系 |
| 2 | x-api-key | Anthropic、Azure、多数自建中转 |
| 3 | x-goog-api-key | Gemini 官方头 |
| 4 | api-key | Azure OpenAI 的另一种写法 |
| 5 | ?key= | 浏览器端(Gemini 支持) |
多个头同时出现时按上表取第一个命中的,顺序与端点无关 —— 同一个请求在任何端点上解出同一个身份。
刻意不接受的两种:
- Cookie 会话。 会把 SDK 调用与控制台登录混成一套身份;而且 Cookie 会被浏览器自动带上,等于给所有网页一次 CSRF 机会。
- 请求体里的
api_key字段。 转发给上游时会被一起带出去,等于把密钥写成 prompt 的一部分。
密钥怎么管
- 明文只在创建时显示一次,之后只保存摘要,取不回来,丢了重新签发。
- 签发时可以设过期时间;过期与停用返回同一个
401 auth.invalid_key(报文相同是刻意的 —— 区分等于告诉攻击者「这把 key 存在但被停了」)。 - 停用立即生效。
- 密钥属于某个人,不是某个团队:那个人被停用,他签发的所有密钥一起失效。
- 没有「每把密钥单独设额度」这回事:额度只有账户级的一个。要按业务线隔离成本,用不同的账号或分组,而不是指望密钥上限。
不要把密钥放进前端
浏览器里的任何密钥都是公开的。要在网页里调用模型,就在你自己的服务端中转一次:密钥留在服务端,浏览器只跟你自己的接口打交道。签发时设一个较短的过期时间,可以缩短泄漏后的可用窗口。
?key= 这个位置存在是因为 Gemini 官方支持它,不是推荐用法:URL 会进浏览器历史、反向代理日志、Referer。
两个命名空间不通用
| 路径 | 鉴权 | 用途 |
|---|---|---|
/v1/**、/v1beta/**、厂商原生路径 | API Key(上面五个位置) | 模型调用 |
/api/** | 登录后拿到的访问令牌 | 控制台、管理、账单 |
拿 API Key 调 /api/** 会被拒(401 auth.key_on_console)。这是刻意的:一个密钥能改自己的余额,等于没有余额。
同理,把 base 写成 <网关地址>/api/v1 不会「碰巧能用」:它会被当成控制台接口,返回 401,而且不会出现在使用日志里 —— 因为它没有进入模型调用,查日志只能验证「没来过」。
相关错误码
| code | 状态码 | 含义 |
|---|---|---|
auth.key_missing | 401 | 五个位置都没有密钥 |
auth.invalid_key | 401 | 密钥无效、已停用,或签发它的账号被停用 |
auth.account_disabled | 403 | 账号被停用 |
auth.key_on_console | 401 | API Key 用在了 /api/** |
完整错误码表在 API 参考。