鉴权与密钥
所有外部读取接口都使用应用 API Key：
Authorization: Bearer whale_consumer_xxxAPI Key 属于接入应用，不属于个人账号，也不用于登录 Portal。服务端从 Key 解析应用身份，客户端不应提交或伪造 consumer_id。
密钥管理
- 每个部署环境和外部系统使用独立 Key，便于审计和吊销。
- Key 只在生成时完整显示一次，不要写入源码、镜像或前端页面。
- 使用 Secret Manager、Key Vault 或受控环境变量保存。
- 轮换时先生成新 Key，完成流量切换后再吊销旧 Key。
- 怀疑泄露时立即在 Portal 吊销并联系平台管理员。
响应语义
| HTTP | code | 含义 | 处理 |
|---|---|---|---|
| 401 | unauthorized | 缺少、无效、过期或已吊销的 Key | 停止重试并检查凭证 |
| 403 | entitlement_denied | 应用没有对应订阅范围 | 缩小查询或申请平台调整订阅 |
| 429 | rate_limit_exceeded | 超过 RPS、突发或并发限制 | 遵循 Retry-After 并降低并发 |
| 429 | quota_exceeded | 达到当日配额 | 等待 UTC 配额窗口重置或申请调整 |
不要把应用密钥放在 URL 查询参数中。日志中只允许记录 Key 前缀，不得记录完整值。