---
title: 鉴权与密钥
description: 应用 API Key 的使用、轮换和错误处理。
---

# 鉴权与密钥

所有外部读取接口都使用应用 API Key：

```http
Authorization: Bearer whale_consumer_xxx
```

API 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 前缀，不得记录完整值。