文档开始使用鉴权
鉴权
三种鉴权头、Key 格式与生命周期、鉴权相关错误。
所有数据面请求（/v1/* 与 /v1beta/*）都必须携带 API Key。为兼容三家 SDK，网关按以下顺序识别三种鉴权头，命中任意一种即可：
| 鉴权头 | 写法 | 常见客户端 |
|---|---|---|
Authorization | Authorization: Bearer sk-sole-…（也接受不带 Bearer 前缀的裸 Key） | OpenAI SDK · Codex |
x-api-key | x-api-key: sk-sole-… | Anthropic SDK · Claude Code |
x-goog-api-key | x-goog-api-key: sk-sole-… | Google GenAI SDK |
不支持用 URL 查询参数（如 Gemini 官方的 ?key=）传 Key：查询串会进入各级访问日志与浏览器历史，泄漏风险高。请一律放在请求头里。
Key 格式与生命周期
Key 以 sk-sole- 开头。完整 Key 只在创建时展示一次，服务端只保存哈希——丢失后无法找回，只能重建。每把 Key 可独立配置：
- 启用/停用：随时一键停用，不删除历史用量。
- 过期时间：适合临时接入或第三方交付场景。
- 消费额度：以 USD 计的上限，可选按天/周/月自动重置；用尽后该 Key 请求被拒（HTTP 402）。
- IP 白名单：限定允许调用的来源 IP，白名单外请求被拒（HTTP 403）。
鉴权相关错误
| 情形 | HTTP | 文案 id |
|---|---|---|
| 未携带 Key | 401 | key_missing |
| Key 不存在或已被删除 | 401 | key_invalid |
| Key 被停用 | 403 | key_disabled |
| Key 已过期 | 403 | key_expired |
| 来源 IP 不在白名单 | 403 | key_ip_denied |
| Key 消费额度用尽 | 402 | key_quota_exhausted |
| 账号被停用 | 403 | account_disabled |
错误响应的形状随请求路径匹配对应 SDK 的格式，文案按账号偏好语言本地化（鉴权失败时按 Accept-Language，默认英文），详见错误码。
安全建议
- 把 Key 放进环境变量或密钥管理器，不要写进源码与配置仓库。
- 不要在浏览器等客户端侧代码里暴露 Key；需要前端直连时，用短期额度 + IP 白名单的专用 Key。
- 按业务拆分多把 Key，便于用量隔离与事故止损（只停用受影响的那把）。
- 定期轮换，临时用途设过期时间与消费额度。