认证与 API Key
Markdown 版发送、创建、限定、轮换和吊销 API Key。
发送 API Key
在每个请求中发送 Authorization: Bearer mb_live_...。令牌是 256 位随机值,不是 JWT,不包含任何可读信息。服务端只保存哈希,并在每个请求上查询验证。
curl https://api.mirabase.dev/v2/whoami \
-H "Authorization: Bearer $MIRABASE_API_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 -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 -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 的步骤如下:
- 调用
POST /v2/api-keys签发新 Key。 - 将调用方切换到新 Key。
- 调用
DELETE /v2/api-keys/{key_id}吊销旧 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 返回)。
