# 创建和使用 API Key


要通过程序读取数据或配置活动，请当前组织的成员创建对应权限的 API Key。负责接入的同事不需要因此更改成员角色。

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

## 打开 API Keys

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

组织内任何成员都可以创建 Key；创建者可以撤销自己创建的 Key，Owner 或 Admin 可以撤销组织内所有 Key。

## 创建数据读取 Key

1. 选择 **Create API Key**（创建 API 密钥），填写 **Name**（名称）。同一组织不能重复使用已有 Active Key 的名称。
2. 选择 **Expires**（有效期）：7d、30d、90d、1y 或 Never；默认 90 天。
3. 在 **Permissions → Data**（权限中的数据访问）开启数据读取。**不选择具体来源时，这把 Key 可读取组织目前及以后拥有的全部订阅**。要缩小范围，展开 **Limit this key to specific subscriptions or campaigns**（把这把 key 限定到指定订阅或 campaign），在 **Campaign access**（活动访问权限）或 **Subscription access**（订阅访问权限）实际勾选目标。只展开列表而不勾选，仍是完整组织范围。
4. 确认组织、范围和有效期，选择 **Create key**（创建密钥）。如需数据使用协议，先阅读并按提示处理。
5. 在 **Your new API key**（你的新 API 密钥） 弹窗保存完整 Key。它只展示一次，后续列表仅显示掩码。
6. 回到列表检查 **Scope、Status、Expires**，在 **Pull from**（拉取来源） 找到目标数据源及其 Subscription ID。

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

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

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

## 创建活动配置 Key

同一表单的 **Permissions → Campaigns**（权限中的活动配置）与 Data 分开。只查看配置选 **Read (`campaign:read`)**；验证、规划或应用候选配置选 **Write (`campaign:author`)**，表单也会选中 Read，以便查看结果。管理者创建 Key 时可编辑的活动决定写入范围；以后新增的活动不会自动加入这份写入授权。Data 下的 **Campaign access** 只控制交付数据来源，不授予编辑权限。

只有接入需要通过 API 发起发布时才选择 **Launch (`campaign:launch`)**。它会同时选中 Read 和 Write，还必须填写大于零的 **Spend cap**（支出上限）及每日或每月窗口。具体发布提案仍由人确认。创建后，用这把 Key 请求 `GET /api/v1/auth/whoami`，核对组织、`scopes` 和 `managed_campaign_ids`，再使用[Campaign API](/zh/api/campaign-api)。授权或目标范围不符时，请 Owner 或 Admin 安排替代 Key；调整 Data 范围不会修复编辑权限。

选了 Write 或 Launch 的 Key 最长有效 90 天，表单会锁定 **1y**（1 年）和 **Never**（永不过期）。到期前请安排新 Key 替换，否则依赖它的程序在到期后会被拒绝；只读和数据读取 Key 仍可选择全部有效期。

## 使用与替换

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

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

Key 以 `hb_live_sk_` 开头。把这个前缀加入密钥扫描规则，误提交的 Key 就能被及时发现。

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

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

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

## 创建受阻

| 情况 | 检查 |
| --- | --- |
| 没有创建按钮 | 当前组织和登录账号；确认后仍缺失时联系支持 |
| Create key 不可用 | Name、Permissions 中至少一项授权、选择 Launch 时有效的 Spend cap，以及列表加载状态 |
| 找不到活动 | 当前组织、归属及活动状态 |
| 只剩掩码 | 无法还原旧 Key，安排替换 |
| 协议或服务错误 | 保留提示[联系支持](/zh/help/support)，不反复创建 |

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