API Key

API Key 让你的后端可以向 Arenza 发送已配置的业务事件。本页按接入顺序说明：需要哪三个值、在哪里获取，以及请求中如何填写。

1. 获取网站 ID

请求地址中的 website_install_id 就填这个值，用来指定哪个网站／品牌连接接收事件。这个 ID 是公开的；知道它不代表有权发送服务端事件。

2. 创建密钥

在同一个 Portal 中打开 Personal Access Tokens。
点击 New token，填写名称。发送事件需选择 Write；只有 Read 不能发送事件。
点击 Create token，复制 arn_pat_…。它只显示一次，就是下文的 API_KEY。

密钥用于证明你的后端有权发起请求。请保存在后端的密钥管理服务中，发送时由后端读取。不要放入浏览器代码、代码仓库或 URL。遗失后请新建，旧明文无法恢复。创建或撤销密钥均需登录 Portal；界面不提供密钥编辑或过期日期设置。

发送前还需确认：密钥具有 Write 权限和目标品牌的访问权限，连接已配置服务端事件，且要发送的事件类型已获允许。创建密钥或安装 SDK 不会自动配置这些事件，也不会创建计费合同。

3. 生成事件去重 ID

webhook-id 是这条事件自身的去重 ID，由你的后端为每条事件生成一个 UUID 并保存。重试同一条事件时复用同一个 UUID；发送另一条事件时另建 UUID。

它不是 Cookie 里的访客 ID。访客 ID 是 arenza_visitor_id，由 SDK 存在浏览器 Cookie 中，表示「哪个访客产生了事件」：前端通过 getVisitorId() 读取后传给你的后端，后端上报时放进请求体的 attribution.visitor_id。webhook-id 表示的则是「这是哪一条事件」——同一个访客产生多条事件时，访客 ID 相同，但每条事件各有自己的 webhook-id。

UUID 是采用标准格式的唯一标识，不是任意填写的名称。例如，Python 的 uuid 模块可通过 str(uuid.uuid4()) 生成。

它用于标识这条事件，不用于证明权限。它不是密钥，不需要从 Portal 获取，也不是服务端回执。

4. 填写请求

将 {website_install_id} 换成公开的 arz_pub_… ID，将 <API_KEY> 换成秘密的 arn_pat_… 密钥，将 <UUID> 换成已保存的事件去重 UUID。保留密钥前的 Bearer 。Content-Type: application/json 表示请求正文采用 JSON 格式。

下面仅展示请求方法、路径和请求头，不是完整请求。正文需要哪些字段，以及完整的 Python／Go 示例，请看服务端事件。请求由后端发往 https://api.arenza.ai，不要在浏览器中发送。

POST /api/v1/billing-events/{website_install_id}
Authorization: Bearer <API_KEY>
Content-Type: application/json
webhook-id: <UUID>

轮换撤销

新建密钥，更新后端并验证请求，再在原令牌列表点击 Revoke 撤销旧密钥。旧密钥的后续请求会被拒绝。

查看响应

401：密钥缺失、无效或已撤销。
403 insufficient_scope：缺少 Write。
404：连接不可用或无品牌访问权限。
422 server_event_not_configured：安装 ID 仅用于采集，未配置服务端事件。
422 event_handle_not_allowed：事件类型未获允许。

202 只表示接收或入队，不代表业务结果、归因或计费已完成。更多响应见接口参考。

密钥只能用于支持它的接口，并非所有 Arenza API。连接 AI 助手请看 MCP Server，该方式使用 OAuth，不使用这里的密钥。