API Key

API Key 用于明确支持 Personal Access Token 的服务端接口，不是所有 API 的通用凭据，也不用于 MCP OAuth。

创建密钥

1. 打开 Portal → Personal Access Tokens。
2. 点击 New token，填写名称，按需选择 Read 或 Write。
3. 点击 Create token，复制 arn_pat_…。明文只显示一次。

通过后端 secret manager 保存并注入密钥，不要放入浏览器、代码仓库或 URL。遗失后请新建，不能恢复旧明文。界面不提供密钥编辑或过期日期设置。

权限边界

按接口要求选择最小权限。事件写入需要 Write 和目标品牌的访问权限，还需要品牌已配置事件连接及允许的事件类型。创建 Key 不会创建计费合同。

服务端事件 使用：

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

公开的 arz_pub_… 安装 ID 用于定位连接，不能替代秘密 Key。官方 /me 下的令牌管理接口使用 Clerk 登录会话；不能用 Key 创建 Key。

轮换撤销

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

排查错误

事件接口的常见响应：

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

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