# 创建和使用 API Key


要通过程序读取数据，请当前组织的 **Owner 或 Admin** 创建 API Key。负责接入的同事可以使用这把 Key，不需要因此更改成员角色。

已有完整 Key 和 Subscription ID？直接前往[通过 API 获取数据](/versions/2026-10-08/api/api-data)。

## 打开 API Keys

在 Developer 左下角点击头像、用户名和组织名区域，选择 **API Keys**，或打开 [API Keys 页面](https://developer.humanbased.ai/api-keys)。先确认当前组织。

Member 可以查看列表和取数说明，但不显示创建按钮。此时请当前组织的 Owner 或 Admin 完成下面的创建步骤。

## 创建数据读取 Key

1. 选择 **Create API Key**，填写 **Name**。同一组织不能重复使用已有 Active Key 的名称。
2. 选择 **Expires**：7d、30d、90d、1y 或 Never；默认 90 天。
3. 在 **Campaign access** 选择本组织的 Campaign，或在 **Subscription access** 选择已有有效订阅。至少选择一项。
4. 确认组织、范围和有效期，选择 **Create key**。如需数据使用协议，先阅读并按提示处理。
5. 在 **Your new API key** 弹窗保存完整 Key。它只展示一次，后续列表仅显示掩码。
6. 回到列表检查 **Scope、Status、Expires**，在 **Pull from** 找到目标数据源及其 Subscription ID。

请求时需要两个值：**API Key** 用于认证，**Subscription ID** 指定要读哪份订阅。使用页面给出的 Subscription ID，不用 Campaign ID 替代。

**Campaign access** 可选择本组织 live、paused 或 finished 的 Campaign，每把 Key 最多 25 个；草稿和归档不在此范围。创建时会建立或复用对应订阅，无需先到 Marketplace 购买自有数据。

Campaign 显示 **partial** 时，会复用已有订阅较窄的任务或筛选范围，不会自动扩大授权。读取外部数据则需要组织先有对应订阅。

## 使用与替换

将 Key 保存在受控的服务端或密钥管理工具中。程序使用下面的请求头认证，无需创建者保持网页登录：

```http
Authorization: Bearer <API_KEY>
```

Active 状态仍需同时检查 Expires；已过期的 Key 不可用。丢失完整 Key 时，由 Owner 或 Admin 创建替代凭证、更新程序配置，再撤销不再使用的旧 Key。

完整 Key 不应出现在公开前端、截图或文档中。

撤销使用 **Revoke** 并确认，会影响所有使用这把 Key 的程序。

## 创建受阻

| 情况 | 检查 |
| --- | --- |
| 没有创建按钮 | 当前组织角色；Member 请 Owner 或 Admin 创建 |
| Create key 不可用 | Name、数据范围和列表加载状态 |
| 找不到 Campaign | 当前组织、归属及 Campaign 状态 |
| 只剩掩码 | 无法还原旧 Key，安排替换 |
| 协议或服务错误 | 保留提示[联系支持](/versions/2026-10-08/help/support)，不反复创建 |

准备好完整 Key 和 Subscription ID 后，继续[获取数据](/versions/2026-10-08/api/api-data)。