安全与配置

保护 API Key 的核心原则是：不要公开、最小权限、定期轮换、可追踪来源。

API Key 如何管理和保护？

推荐做法：

• 不要把 API Key 提交到公开仓库、前端页面、移动端安装包或截图中。
• 在服务端通过环境变量或密钥管理系统读取 API Key。
• 为开发、测试、生产分别创建不同的 API Key。
• 为不同服务或应用分别创建 API Key，便于追踪来源和隔离风险。
• 根据业务需要配置模型权限，并设置有效期。
• 定期轮换 API Key；人员变动、服务下线或怀疑泄露时立即更换。

如果 API Key 可能已经泄露：

1. 立即停用、删除或轮换旧 Key。
2. 创建新 Key，并更新所有依赖该凭据的服务。
3. 检查近期用量、余额变化和异常消耗。
4. 收紧模型权限，并设置更短的有效期。
5. 复盘泄露路径，例如代码仓库、日志、CI 配置或第三方客户端。

API Key 泄露可能造成未授权调用和费用损失。即使只是在测试环境使用，也应按生产密钥的标准保护。

创建后还能再次查看完整 API Key 吗？

不能。完整 API Key 只在创建成功时展示一次，之后控制台只显示脱敏预览。

请在创建弹窗关闭前把 Key 保存到服务端环境变量或密钥管理系统。遗失后无法通过 用户或管理员接口恢复原值，需要创建替代 Key、更新调用方，再删除旧 Key。Docs 中的 AI 接入模板使用 <API_KEY> 占位符，也不会读取历史 Key。

API Key 应该如何传递？

API Key 只能通过请求 Header 传递，推荐使用：

Authorization: Bearer YOUR_API_KEY

也可以使用：

X-API-Key: YOUR_API_KEY

绝不能把 API Key 放入 URL query。Query 参数名 apiKey、api_key、 apikey、x-api-key、key 按大小写不敏感方式匹配，并统一返回 HTTP 400。 即使参数值为空、重复出现，或请求同时携带了有效认证 Header，也会被拒绝。

该规则不会影响普通业务 Query 参数，例如 OAuth 流程使用的 token、 apiKeyId、username 或 pagination_token。