## 查询取数接入路线

以下是推荐阅读顺序，不代表已完成的进度；可选步骤可以跳过。

1. [获取与使用 API Key](/docs/authentication) ← 当前页
2. [完成第一次查询](/docs/quickstart)
3. [关键词与语义检索](/docs/search)
4. [用户、话题、标签与分类](/docs/browse)（可选）
5. [读取内容与历史](/docs/documents)
6. [下载图片与附件](/docs/attachments)（可选）
7. [限流、重试与排错](/docs/production)

**开始前**：确定接入应用及组织管理员；尚无应用或订阅时先按本页链接完成申请。

# 获取与使用 API Key

## 获取密钥与授权

如果你在组织中有密钥管理权限（owner 或 admin），在 [Portal](/docs/portal) 的「接入应用 → 应用密钥」中生成 Consumer API Key。没有这个权限时，向你的组织管理员申请，并通过安全渠道接收密钥。拿到 Key 后即可调用 API，不必先登录 Portal。

同时向组织管理员确认你的应用、环境、数据集、平台和字段授权。生成 Key 不等于获得全部数据访问权限；订阅范围需要单独配置。Collector Key 和内部 Admin Token 不能代替此处的 Consumer API Key。

## 配置调用环境

所有示例统一使用 `WHALE_BASE_URL` 和 `WHALE_API_KEY`。生产服务地址为 `https://www.marsyoo.com`；使用测试环境时，换成组织管理员提供给你的地址与测试 Key。

通过 Secret Manager 或受保护的环境变量注入密钥，也可在 Bash 中交互输入，避免将明文写入命令历史：


```bash
export WHALE_BASE_URL="${WHALE_BASE_URL:-https://www.marsyoo.com}"
read -r -s -p "Consumer API Key: " WHALE_API_KEY
printf '\n'
export WHALE_API_KEY
```


不要打印密钥或将它放入前端。配置后进入[完成第一次查询](/docs/quickstart)验证调用。

## 请求鉴权

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


```http
Authorization: Bearer whale_consumer_xxx
```


API Key 属于接入应用，不属于个人账号，也不用于登录 Portal。服务端从 Key 解析应用身份，客户端不应提交或伪造 `consumer_id`。

## 密钥管理

- 每个部署环境和外部系统使用独立 Key，便于审计和吊销。
- Key 只在生成时完整显示一次，不要写入源码、镜像或前端页面。
- 使用 Secret Manager、Key Vault 或受控环境变量保存。
- 轮换时先生成新 Key，完成流量切换后再吊销旧 Key。
- 怀疑泄露时立即在 Portal 吊销，并联系 Whale 平台支持。

## 响应语义

| HTTP | code | 含义 | 处理 |
| --- | --- | --- | --- |
| 401 | `unauthorized` | 缺少、无效、过期或已吊销的 Key | 停止重试并检查凭证 |
| 403 | `entitlement_denied` | 应用没有对应订阅范围 | 缩小查询或申请平台调整订阅 |
| 429 | `rate_limit_exceeded` | 超过 RPS、突发或并发限制 | 遵循 `Retry-After` 并降低并发 |
| 429 | `quota_exceeded` | 达到当日配额 | 等待 UTC 配额窗口重置或申请调整 |

不要把应用密钥放在 URL 查询参数中。日志中只允许记录 Key 前缀，不得记录完整值。

## 检查与继续

**完成标准**：已通过安全渠道取得 Consumer Key，配置服务地址和环境变量，明确数据及字段授权；不要把密钥粘贴到 Agent 对话。

**推荐下一步**：[完成第一次查询](/docs/quickstart)