API 密钥
API 密钥让网站、应用或您的服务器无需登录界面即可使用项目：发送事件、读取档案、管理分群、旅程和群发。密钥在“设置”→“API 密钥”中创建和撤销。
“所有者”“管理员”和“经理”可以看到此板块。“所有者”和“管理员”可以创建和撤销密钥。
密钥类型
| 写入（Write） | 私密（Secret） | |
|---|---|---|
| 前缀 | cdp_wk_ |
cdp_sk_ |
| 允许的操作 | 仅发送事件 | 发送事件，以及按所选权限在项目中执行操作 |
| 使用场景 | 网站代码、移动应用、服务器 | 仅限您的服务器 |
| 能否公开 | 可以，它在网站页面代码中可见 | 不可以，请妥善保密 |
| 请求限额 | 每分钟 6000 次 | 每分钟 1200 次（默认） |
写入密钥本质上是公开的：它出现在网站每个页面的代码中。它只能用于发送事件，因此泄露不会导致数据被访问。为防止其他网站冒用您的名义发送事件，您可以在“网站”板块中指定允许使用该密钥的域名，参见接入网站。
私密密钥提供对项目数据的服务端访问。切勿将其放入页面代码、移动应用或公开代码仓库。
如何创建密钥
- 打开“API 密钥”。
- 在“新建密钥”卡片中填写“名称”，以便日后了解密钥的用途，例如“网站”或“网上商店服务器”。
- 选择“类型”：写入或私密。
- 对于私密密钥，勾选“密钥权限”：只选择集成真正需要的权限。
- 点击“创建密钥”。
创建后，页面顶部会立即显示完整的密钥。点击“复制”并妥善保存，例如保存在密码管理器或服务器的环境变量中。私密密钥仅显示一次：我们只存储其指纹，无法找回密钥。如果密钥丢失，请创建新密钥并撤销旧密钥。
网站使用的写入密钥更适合直接在“网站”板块中创建：它会自动填入安装代码，并可随时查看，参见接入网站。
密钥表格中显示名称、创建者和创建时间、类型、密钥开头（例如 cdp_sk_a1b2…）、权限数量以及最近使用时间。
私密密钥的权限
您只能为密钥授予自己拥有的权限。权限作用于整个项目，无法将密钥限定于特定旅程或分群。
| 权限 | 开放的功能 |
|---|---|
| 读取档案 | 按标识符获取档案及其事件 |
| 未脱敏的个人数据 | 以明文显示邮箱、电话等个人数据；没有此权限时这些数据会被脱敏 |
| 修改档案和同意 | 群发同意、绑定 Telegram |
| 删除档案（GDPR） | 应客户要求删除档案 |
| 事件和属性目录 | 事件列表和档案属性 |
| 读取 / 修改分群 | 查看、创建、修改、删除和重新计算分群 |
| 读取旅程和报告；编辑草稿并添加参与者；发布、暂停和归档旅程 | 管理旅程 |
| 读取群发和报告；创建和编辑群发；启动、暂停和取消群发 | 管理群发 |
| 读取商品目录和推荐；上传和删除商品 | 商品和推荐 |
| 分析 | 报告 |
示例：用于从 CRM 同步 VIP 客户的密钥，只需“读取分群”和“修改分群”权限即可。
通过私密密钥执行的所有操作都会以该密钥的名义记录在项目审计日志中，参见项目设置、套餐与审计。
如何撤销密钥
- 在表格中找到密钥并点击“撤销”。
- 确认操作。
使用该密钥的请求会立即失效（返回 401）。已撤销的密钥会保留在列表中并标记为“已撤销”，以便查看其历史记录。密钥无法恢复，如有需要请创建新密钥。
如果密钥可能已被外人获取、有权访问密钥的员工已离职，或集成已不再使用，请立即撤销密钥。
注意事项
- **限额。**超出请求限额或套餐的每月事件配额时，API 会返回
429。请均匀分配发送量，并在暂停后重试请求。 - **安全地更换密钥。**创建新密钥，在服务器上更新，确认请求正常（查看“最近使用”字段），然后再撤销旧密钥。
- **每个集成使用单独的密钥。**这样可以在审计日志中看清是谁做了什么，泄露时只需撤销一个密钥。
- 如何从服务器发送事件和调用 API，请参阅服务器端集成。