API 鉴权头速查
各家接口的鉴权方式不统一：OpenAI 及其兼容生态用 Authorization 请求头携带 Bearer 令牌，Anthropic 用 x-api-key 并额外要求接口版本头，Google 用 x-goog-api-key 或云平台的 IAM 凭证，自建网关则常见自定义头。写客户端封装时把这些差异收敛到一处，业务代码只拿一个统一的调用入口。
基本信息
| 通用原则 | 密钥只放服务端，出现在请求头里而不是 URL 参数 |
|---|---|
| 常见头名 | Authorization、x-api-key、x-goog-api-key |
| 附加头 | 接口版本头、内容类型头，缺一即可能被拒 |
| 网关做法 | 内部自定义头加内网隔离，对外只暴露一个入口 |
| 排查顺序 | 先看头名与拼写，再看密钥有效期与额度，最后查区域与权限 |
常见服务鉴权对照
| 服务 | 鉴权方式 | 注意点 |
|---|---|---|
| OpenAI 与兼容生态 | Authorization: Bearer 加密钥 | 兼容端点大多沿用这一形式 |
| Anthropic | x-api-key 加接口版本头 | 版本头缺失会直接报错 |
| x-goog-api-key，或云平台 IAM 凭证 | 不要把密钥拼进 URL 查询参数 | |
| 自建网关 | 自定义头加内网白名单 | 网关统一持有上游密钥，业务侧不接触 |
典型使用场景
- 多模型接入：在封装层按提供方自动选择鉴权方式
- 统一网关：业务只带内部令牌，网关再换成真实上游密钥
- 临时排障：用命令行快速验证密钥与头是否正确
- 密钥轮换：新旧密钥并行一段时间后再下线旧密钥
- 权限分层：只读用途与写入用途使用不同密钥
三种鉴权写法
三种鉴权写法
curl -s $BASE/v1/chat/completions -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" -d '{...}' # 兼容生态
curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" -d '{...}'
curl -s "https://generativelanguage.googleapis.com/v1beta/models/$MODEL:generateContent" -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" -d '{...}'
# 所有密钥都应从环境变量或密钥管理服务读取，不要写进代码与镜像常见鉴权事故
| 事故 | 原因 | 规避 |
|---|---|---|
| 密钥对全网可见 | 前端直连模型接口并携带密钥 | 前端只调自有后端，密钥留在服务端 |
| 密钥进日志 | 把完整请求头打进访问日志 | 日志侧对鉴权头做脱敏 |
| 密钥进 URL | 用查询参数传密钥 | 一律改为请求头传递 |
| 单密钥混用 | 测试与生产共用一个密钥 | 按环境与用途拆分，各自设额度 |
401 与 403 的差别值得留意：前者通常是密钥无效或格式错误，后者多为权限、区域或配额限制，排查方向完全不同。
已经出现在仓库历史、镜像层或聊天记录里的密钥要直接作废重发，仅轮换文件里的那一处并不安全。