认证与 API Key

认证格式

每次请求都需要在 Authorization Header 里带一个以 sk- 开头的 API Key：

http
POST /v1/chat/completions HTTP/1.1
Host: api.aicodedog.com
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{...}

没带、带错或者带的是失效 Key，会立即返回 401 Unauthorized。

签发、查看、回收

所有操作都在控制台 API Key 管理 页面：

• **签发**：点 新建密钥，可设置备注（建议写「生产 / 开发 / CI / 实验」等用途）。完整密钥**仅在创建窗口展示一次**，关掉后不再显示。
• **轮换**：先创建一把新 Key 替换到代码里，确认无误后**再**回收旧 Key。这样切换是无感的。
• **回收**：点 Key 行的 禁用。立即生效，被禁用的 Key 后续任何调用都会 401。
• **查看**：列表只显示前 4 位 + 后 4 位（如 sk-abcd...wxyz），便于识别但不会泄漏完整 Key。

权限作用域

目前 API Key 是**租户级**——同一账号下的所有 Key 共享同一份余额、同一份调用配额。这意味着：

• 给团队不同成员发不同 Key 是为了**审计**（每次调用都记录哪把 Key 发出），而不是隔离配额。
• 如果你要给客户分账，请走 OEM 子租户——每个子租户有独立余额、独立 Key 池。

安全最佳实践

• **永不写死在代码里**。Key 必须从环境变量、Secret Manager、Vault 之类的运行时来源读取。
• **永不放在前端**。任何浏览器端、APP 端、客户端代码都不能直接持有 Key——攻击者打开 DevTools 就能拿到。前端要走你自己的后端代理。
• **每个环境/服务一把单独的 Key**。生产、staging、CI、个人开发各一把，泄漏一把不影响其他。
• **定期轮换**。建议每 90 天轮一次。（这是 PCI/SOC 2 合规的硬指标。）
• **监控异常用量**。在控制台 用量 页设置每日上限提醒，被刷会及时告警。

IP 白名单（可选）

每把 Key 可以绑定一个 CIDR 列表，只允许列表内的源 IP 调用。适合服务器端固定出口的场景：

json
{
  "label": "production-api",
  "allowedIps": ["203.0.113.0/24", "198.51.100.42/32"]
}

列表外的 IP 调用会立即返回 403 Forbidden，并在审计日志里留痕。