API 认证
所有 API 请求都必须在 HTTP Header 中包含您的 API Key 进行认证。本文档将指导您如何安全地使用 API Key。
认证概述
TurningAPI 使用基于 API Key 的认证机制。每个 API 请求都需要在 HTTP Header 中包含有效的 API Key。 您可以在 控制台 创建和管理您的 API Key。
认证 Header
在发送 API 请求时，您需要在 HTTP Header 中包含以下认证信息：
Authorization: Bearer YOUR_API_KEY重要提示
Header 名称必须为 Authorization， 值必须以 Bearer 开头，后面跟您的 API Key。
代码示例
以下是在不同编程语言中使用 API Key 进行认证的示例：
curl -X POST https://api.turning.info/v1/person/verify \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "张三", "id_card": "110101199003071234" }'
安全最佳实践
不要在客户端代码中暴露 API Key
永远不要将 API Key 硬编码到前端代码、移动应用或任何可能被用户访问的代码中。API Key 一旦泄露，可能被恶意使用。
❌ 错误示例：
const apiKey = "sk-1234567890abcdef"; // 不要这样做！
使用环境变量
将 API Key 存储在环境变量中，这样既安全又便于在不同环境间切换。
✅ 正确示例：
const apiKey = process.env.TURNING_API_KEY;
使用密钥管理服务
在生产环境中，建议使用专业的密钥管理服务（如 AWS Secrets Manager、Azure Key Vault、HashiCorp Vault 等）来存储和管理 API Key。
定期轮换 API Key
定期更换 API Key 可以降低泄露风险。如果怀疑 API Key 已泄露，请立即在控制台中撤销并创建新的 Key。
不要将 API Key 提交到版本控制系统
确保将包含 API Key 的文件添加到 .gitignore 中，避免意外提交到 Git 仓库。
常见认证错误
401
401 Unauthorized - API Key 无效或未提供
这通常表示：
- API Key 未在 Header 中提供
- API Key 格式不正确（缺少 "Bearer " 前缀）
- API Key 已过期或被撤销
- API Key 不属于当前账户
解决方案：
检查 Header 格式：Authorization: Bearer YOUR_API_KEY
403
403 Forbidden - 无权访问该 API
这通常表示：
- API Key 没有访问该特定 API 的权限
- 您的账户套餐不支持该 API
- API Key 的权限范围受限
解决方案：
检查 API Key 权限或升级您的账户套餐