创建和使用 API Key

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

已有完整 Key 和 Subscription ID？直接前往通过 API 获取数据。

打开 API Keys

在 Developer 左下角点击头像、用户名和组织名区域，选择 API Keys（API 密钥），或打开 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 只控制交付数据Developer 获准读取的数据产出，有独立的交付状态和访问状态来源，不授予编辑权限。

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

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

使用与替换

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

Authorization: Bearer <API_KEY>

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

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

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

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

创建受阻

准备好完整 Key 和 Subscription ID 后，继续获取数据。