API 密钥管理
API 密钥管理
API 密钥用于程序化访问欣悦互通的 API 接口。当您需要通过脚本、第三方系统或自动化工具调用 API 时，可以使用 API 密钥进行身份认证，无需每次输入账号密码。
本篇介绍 API 密钥的创建、启用/禁用、删除以及安全使用规范。
API 密钥概念
API 密钥是一串长随机字符串，作为调用 API 时的身份凭证。与账号密码相比，API 密钥具有以下特点：
- 可独立启用/禁用：不影响账号登录。
- 可随时吊销：泄露后可立即删除，不影响其他密钥。
- 继承账号权限：密钥的访问范围等于所属账号的角色权限。
- 长期有效：不会因登录过期而失效，直到被手动删除或禁用。
!WARNING API 密钥等同于账号凭证，请像保管密码一样保管。切勿将密钥提交到代码仓库、写入客户端代码或通过不安全渠道传输。
创建密钥
- 登录管理后台，进入「个人中心 → API 密钥」。
- 点击「新增密钥」按钮。
- 在弹窗中填写：
- 密钥名称（便于识别用途，如「数据同步脚本」）
- 过期时间（可选，留空则永久有效）
- 点击「确定」创建。
创建成功后，系统会一次性显示完整密钥字符串，请立即复制保存。
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
!WARNING 出于安全考虑，完整密钥仅在创建时显示一次，之后只能查看掩码形式（如
sk-****...****）。请务必在创建后立即复制保存到安全的密钥管理工具中。
切换启用/禁用
每个密钥可独立启用或禁用，禁用后该密钥的所有 API 调用将被拒绝。
- 在 API 密钥列表中找到目标密钥。
- 点击状态列的开关切换启用/禁用。
- 切换即时生效，无需确认。
禁用密钥不会删除它，可随时重新启用。系统调用 POST /api/api-keys/{id}/toggle 完成切换。
!TIP 当怀疑密钥泄露但尚未确认时，可先禁用密钥暂停访问，排查清楚后再决定启用或删除。
删除密钥
删除密钥是永久操作，删除后该密钥立即失效且无法恢复。
- 在 API 密钥列表中点击操作列的「删除」。
- 在确认弹窗中点击「确定」。
删除后，所有使用该密钥的脚本或系统将无法继续访问 API，请提前通知相关方并创建新密钥替换。
密钥安全最佳实践
1. 最小权限原则
为 API 密钥创建专用账号，仅分配必要的角色和权限。避免使用管理员账号的密钥进行日常自动化操作。
2. 定期轮换
建议每 90 天轮换一次密钥：创建新密钥 → 更新脚本配置 → 验证可用 → 删除旧密钥。
3. 设置过期时间
为临时用途的密钥设置过期时间，避免遗忘后长期暴露。
4. 环境变量管理
将密钥存储在环境变量或密钥管理服务（如 Vault、AWS Secrets Manager）中，切勿硬编码到源代码。
export XYHT_API_KEY="sk-xxxxxxxxxxxxxxxx"
5. 监控异常调用
定期查看活动日志（GET /api/activity-log），关注异常的 API 调用频率或来源 IP。
访问 API 示例
使用 Bearer Token 认证
所有 API 请求需在 Header 中携带 Authorization 字段：
GET /api/geo/projects HTTP/1.1
Host: api.example.com
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json
使用 cURL 调用
curl -X GET "https://api.example.com/api/geo/projects" \
-H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json"
使用 JavaScript 调用
const response = await fetch('https://api.example.com/api/geo/projects', {
headers: {
'Authorization': `Bearer ${process.env.XYHT_API_KEY}`,
'Content-Type': 'application/json',
},
});
const data = await response.json();
!NOTE API 调用受速率限制约束（令牌桶 + 滑动窗口）。如调用频率超限，将返回
429 Too Many Requests状态码，请参考 配额与用量预警 了解限额详情。