跳到主要内容
开发者文档
文档目录

认证与 API Key

Markdown 版

发送、创建、限定、轮换和吊销 API Key。

发送 API Key

在每个请求中发送 Authorization: Bearer mb_live_...。令牌是 256 位随机值,不是 JWT,不包含任何可读信息。服务端只保存哈希,并在每个请求上查询验证。

curl
curl https://api.mirabase.dev/v2/whoami \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
Key 只保存在服务端。不要写入前端代码、移动应用或公开仓库。怀疑泄露时立即吊销。

只有 GET /llms.txt 和 GET /v2/openapi.yaml 不需要凭据。

在控制台创建 API Key

控制台 提供 API Key 的创建、收窄、轮换和吊销。第一个 Key 在这里创建:注册不会自动签发 Key。明文只显示一次。

控制台的登录会话用于管理账户,也用于控制台自身的功能(文件列表与删除、处理进度、检索测试台、请求日志)。读取文件内容和写入文件只接受 API Key。账户待审批期间,登录会话仅可管理 API Key、查看账户信息和只读列表,其余请求返回 403 account_pending_approval。

通过 API 创建 API Key

POST /v2/api-keys 签发 Key。只有 tenant_admin 能签发,Agent 不能为自己签发;新 Key 的能力、Space 范围和到期时间都不能超出签发者。token 只在这次响应里出现,请立即保存。

curl
curl -X POST https://api.mirabase.dev/v2/api-keys \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": "'$PRINCIPAL_ID'", "name": "ci-reader",
       "grant_capabilities": ["knowledge:read"],
       "allowed_space_ids": ["'$SPACE_ID'"],
       "expires_at": "2027-01-01T00:00:00Z"}'

在有团队的账户中,Admin 能管理哪些主体和 Key,见 签发 API Key 的说明;Owner 不受这些限制。

按元数据限定 API Key

签发 Key 时传入 metadata_scope,这个 Key 只能看到带有对应元数据标签的 Entry。不同元数据键之间是“且”,同一个元数据键的多个值之间是“或”。这类 Key 能调用的操作见 metadata_scope 参数,写入时的标签规则见 DevMetadataScope。

curl
curl -X POST https://api.mirabase.dev/v2/api-keys \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": "'$PRINCIPAL_ID'", "name": "acme-agent",
       "grant_capabilities": ["knowledge:read", "knowledge:answer", "knowledge:write"],
       "metadata_scope": {"customer": ["acme", "shared"]}}'
  • 范围由服务端在每个请求上检查,调用方无法在请求里绕过它。
  • 近似文档的取代和记忆的修订只发生在范围键上取值相同的 Entry 之间,一个客户的写入不会影响另一个客户的内容。
  • 账户记忆没有标签,带范围的 Key 无法读取。
  • 通过 MCP 连接时,tools/list 只向带范围的 Key 列出它能调用的工具。带范围的 Key 也可以在 控制台 的 API Key 页面签发。
  • 范围不隐藏 Space 本身的名称和 external_id。要在最终用户之间做硬隔离,请为每个用户建一个 Space,见 一个最终用户一个 Space。

查看 API Key 的权限

GET /v2/whoami 同时返回主体、Key 和有效能力。收到 403 时,先查看此接口的响应:如果 effective_capabilities 比 principal.capabilities 窄,或者 key.allowed_space_ids 有值,限制来自 Key,不是主体。有效能力的计算方式见 能力。

轮换或替换 API Key

POST /v2/api-keys/{key_id}/rotate 在一个事务内签发新 Key 并吊销旧 Key,没有重叠期。Key 不能轮换自身:一旦响应丢失,调用方将失去可用的凭据。替换当前正在使用的 Key 的步骤如下:

  1. 调用 POST /v2/api-keys 签发新 Key。
  2. 将调用方切换到新 Key。
  3. 调用 DELETE /v2/api-keys/{key_id} 吊销旧 Key。
如果签发响应丢失,旧 Key 仍可使用,换一个 Idempotency-Key 重新签发即可。未使用的 Key 会保留在 GET /v2/api-keys 中,直至管理员将其吊销。

查找未使用的 API Key

每个 Key 都有 last_used_at,即它最近一次调用接口的时间(见 DevApiKey)。清理闲置的 Key、确认发出的 Key 是否已开始使用,都可以依据这个字段;控制台 的 Key 列表也显示它。

吊销 API Key

DELETE /v2/api-keys/{key_id} 返回后,这个 Key 的下一个请求返回 401,且已发起的在途写入也无法提交。吊销不级联:处置泄露时,按每个 Key 的 issued_by_key_id 查出它签发过的 Key,逐个吊销。

删除账户

要删除账户及其全部数据,请联系我们,并提供账户的邮箱和 tenant_id(由 GET /v2/whoami 返回)。

  • 数据删除后无法恢复。请先用 导出 保存需要保留的文件;导出只含文件,不含记忆和版本历史。
  • 如果只需删除部分内容,无需联系我们:用 彻底删除 删除文件,用 遗忘 删除记忆。

下一步

  • SDK:安装客户端,无需手动构造请求。
  • 权限:能力的计算方式,以及如何将 Key 限制在特定 Space 和目录。
  • 连接 Agent:为 Agent 配置独立的主体和 Key。