API 密钥

为智能体与下游系统签发可限定权限、可随时撤销的 API 密钥。

API 密钥（API key）让智能体、CLI、SDK 和下游系统以你的身份程序化访问 Busabase 的 /api/v1 接口。一个密钥就是一份凭证：它能做什么，由你在创建时选定的权限级别决定；它一直有效，直到过期或被删除。

创建 API 密钥：填写名称、选择过期时间与权限级别。

创建 API 密钥——名称、过期时间与权限级别，三项都在创建时一次定好。

创建 API 密钥

打开 Account → API Keys，点击 Create New Key。

填写名称（便于日后辨认用途，例如「内容智能体」）、过期时间、权限级别，然后点击 Create。

密钥只显示一次

创建完成后请立刻复制并妥善保存。页面关闭后无法再次查看，只能删除后重建。

创建时可选择：

选项	说明
永不过期	长期集成使用；需自行轮换
7 天 / 30 天 / 90 天 / 1 年	有明确期限，适合临时任务或定期轮换

默认 30 天，最长 1 年。密钥过期后继续使用会返回 401，需要重新创建。

每个密钥有且只有一个权限级别，高级别向下包含低级别：

级别	界面名称	可以做什么	不能做什么
`read`	只读	在登录用户的权限范围内查看数据	修改工作区内容
`changeRequest`	写 Change Request	查看数据，并提交变更提案	合并（merge）或直接应用变更
`write`	写入数据	查看、提交提案、审核并合并变更，以及直接编辑内容	管理操作与永久删除
`manage`	管理	包含写入权限、管理操作和永久删除节点	—

给智能体用，通常 changeRequest 就够了。 它能读取数据、提出变更，但不能自行合并自己提交的提案——变更仍需人工在收件箱里审核。只有在确有必要时，才授予 write 或 manage。

创建后仍可改名与调整权限级别：密钥本身的值和有效期保持不变；提升权限时会要求二次确认，因为所有已持有该密钥的调用方都会立即获得新增权限。

一个密钥属于你的账号，而不是某一个工作区——它在你所属的所有 workbench 空间（Bases、记录、Change Request、节点）中都可用。

要指定目标空间，请在请求中带上 x-busabase-space 头（CLI / SDK 对应环境变量 BUSABASE_SPACE_ID）。如果你属于多个空间却没有指定，请求会因为目标不明确而被拒绝，Busabase 不会替你猜。

调用 GET /api/v1/auth 可以查看当前生效的目标空间，以及你所属的全部空间。

此外，密钥的权限级别是上限：实际能做什么，还要与你在该空间里的角色权限取交集。

把密钥放进 Authorization 头即可：

curl https://busabase.com/api/v1/auth \
  -H "Authorization: Bearer $BUSABASE_API_KEY" \
  -H "x-busabase-space: $BUSABASE_SPACE_ID"

具体的请求形状与示例见 REST API，完整端点见 OpenAPI 参考。

一个智能体一把密钥。 不要多个智能体共用同一把密钥，否则权限与用量都难以区分。这样，你就可以通过 Busabase Insights 区分并统计出每个智能体分别做出了哪些 Change Request 和提案。
遵循最小权限。 从能完成任务的最低级别开始，需要用更高权限时再单独签发。
设置过期时间。 临时任务用短期密钥，长期集成定期轮换。
不要写进代码仓库。 CI / 本地开发通过环境变量传入（BUSABASE_API_KEY、BUSABASE_SPACE_ID）。
怀疑泄露就立即删除。 删除后使用该密钥的所有调用方会立刻无法认证（见下）。

Account → API Keys 的列表展示每个密钥的名称、密钥前缀、创建时间、过期时间、权限级别与操作。

现象	可能原因与处理
`401` 未授权	密钥无效、已过期、已被删除，或所属账号被封禁。确认密钥正确，必要时重建。
提示目标空间不明确	你属于多个空间却没带 `x-busabase-space`。补上目标空间 ID。
`403` 禁止访问	密钥的权限级别不足以执行该操作（例如用 `changeRequest` 去合并变更）。改用更高权限的密钥，或改由人工操作。

另请参阅：核心概念 · 快速开始

其他接入方式：接入方式总览 · CLI · SDK · MCP · REST API · OpenAPI · Webhook