# 认证与 API Key

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

## 发送 API Key

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

```bash
curl https://api.mirabase.dev/v2/whoami \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

> **注意：** Key 只保存在服务端。不要写入前端代码、移动应用或公开仓库。怀疑泄露时立即吊销。

只有 [`GET /llms.txt`](https://mirabase.io/zh/developers/api/discovery.md#discovery-llms) 和 [`GET /v2/openapi.yaml`](https://mirabase.io/zh/developers/api/discovery.md#discovery-openapi) 不需要凭据。

## 在控制台创建 API Key

[控制台](https://console.mirabase.dev) 提供 API Key 的创建、收窄、轮换和吊销。第一个 Key 在这里创建：注册不会自动签发 Key。明文只显示一次。

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

## 通过 API 创建 API Key

[`POST /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create) 签发 Key。只有 `tenant_admin` 能签发，Agent 不能为自己签发；新 Key 的能力、Space 范围和到期时间都不能超出签发者。`token` 只在这次响应里出现，请立即保存。

curl:

```bash
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"}'
```

TypeScript:

```ts
const key = await mirabase.keys.create({
  actor_id: principalId,
  name: "ci-reader",
  grant_capabilities: ["knowledge:read"],
  allowed_space_ids: [spaceId],
  expires_at: "2027-01-01T00:00:00Z",
});
```

Python:

```python
key = mb.keys.create({
    # The principal the key acts as: here, yourself.
    "actor_id": me["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](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create) 的说明；Owner 不受这些限制。

## 按元数据限定 API Key

签发 Key 时传入 `metadata_scope`，这个 Key 只能看到带有对应元数据标签的 Entry。不同元数据键之间是“且”，同一个元数据键的多个值之间是“或”。这类 Key 能调用的操作见 [metadata_scope 参数](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create.body.metadata_scope)，写入时的标签规则见 [DevMetadataScope](https://mirabase.io/zh/developers/api/schemas.md#DevMetadataScope)。

```bash
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 也可以在 [控制台](https://console.mirabase.dev) 的 API Key 页面签发。
- 范围不隐藏 Space 本身的名称和 `external_id`。要在最终用户之间做硬隔离，请为每个用户建一个 Space，见 [一个最终用户一个 Space](https://mirabase.io/zh/developers/concepts.md#space-per-user)。

## 查看 API Key 的权限

[`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) 同时返回主体、Key 和有效能力。收到 403 时，先查看此接口的响应：如果 `effective_capabilities` 比 `principal.capabilities` 窄，或者 `key.allowed_space_ids` 有值，限制来自 Key，不是主体。有效能力的计算方式见 [能力](https://mirabase.io/zh/developers/permissions.md#capabilities)。

## 轮换或替换 API Key

[`POST /v2/api-keys/{key_id}/rotate`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-rotate) 在一个事务内签发新 Key 并吊销旧 Key，没有重叠期。Key 不能轮换自身：一旦响应丢失，调用方将失去可用的凭据。替换当前正在使用的 Key 的步骤如下：

1. 调用 [`POST /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-create) 签发新 Key。
2. 将调用方切换到新 Key。
3. 调用 [`DELETE /v2/api-keys/{key_id}`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-revoke) 吊销旧 Key。

> **说明：** 如果签发响应丢失，旧 Key 仍可使用，换一个 `Idempotency-Key` 重新签发即可。未使用的 Key 会保留在 [`GET /v2/api-keys`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-list) 中，直至管理员将其吊销。

## 查找未使用的 API Key

每个 Key 都有 `last_used_at`，即它最近一次调用接口的时间（见 [DevApiKey](https://mirabase.io/zh/developers/api/schemas.md#DevApiKey.last_used_at)）。清理闲置的 Key、确认发出的 Key 是否已开始使用，都可以依据这个字段；[控制台](https://console.mirabase.dev) 的 Key 列表也显示它。

## 吊销 API Key

[`DELETE /v2/api-keys/{key_id}`](https://mirabase.io/zh/developers/api/api-keys.md#apikeys-revoke) 返回后，这个 Key 的下一个请求返回 401，且已发起的在途写入也无法提交。吊销不级联：处置泄露时，按每个 Key 的 `issued_by_key_id` 查出它签发过的 Key，逐个吊销。

## 删除账户

要删除账户及其全部数据，请[联系我们](https://mirabase.app/contact)，并提供账户的邮箱和 `tenant_id`（由 [`GET /v2/whoami`](https://mirabase.io/zh/developers/api/identity.md#identity-whoami) 返回）。

- 数据删除后无法恢复。请先用 [导出](https://mirabase.io/zh/developers/sync.md#export) 保存需要保留的文件；导出只含文件，不含记忆和版本历史。
- 如果只需删除部分内容，无需联系我们：用 [彻底删除](https://mirabase.io/zh/developers/files.md#delete) 删除文件，用 [遗忘](https://mirabase.io/zh/developers/memory.md#govern) 删除记忆。

## 下一步

- [SDK](https://mirabase.io/zh/developers/sdks.md)：安装客户端，无需手动构造请求。
- [权限](https://mirabase.io/zh/developers/permissions.md)：能力的计算方式，以及如何将 Key 限制在特定 Space 和目录。
- [连接 Agent](https://mirabase.io/zh/developers/agents.md)：为 Agent 配置独立的主体和 Key。
