# API key

Source: https://docs.simail.ai/zh/api/api-keys/

> 列出并查看你的 key 以及由它派生的 key；可以改名、收紧权限、提前过期或吊销。创建 key 只能由人完成。

```json
{
  "api_key_id": "key_01JZX3S5V7W9X1Y3Z5A7B9C1D5",
  "name": "shop-helper agent",
  "prefix": "sk_3f9a2c1b",
  "scope_type": "inbox",
  "scope_id": "shop-helper@simail.email",
  "permissions": ["inbox_read", "message_read", "draft_write", "message_send"],
  "parent_api_key_id": null,
  "created_via": "console",
  "claimed": true,
  "expires_at": null,
  "last_used_at": "2026-10-18T17:05:40Z",
  "created_at": "2026-10-18T16:45:00Z"
}
```

创建之后密钥不再返回；`prefix` 帮你辨认一把 key。`created_via` 取值为 `console`、`agent_signup` 或 `oauth`（用 OAuth 接上的 MCP 客户端）。

## 列出 key

`GET /v0/api-keys`

任何有效的 key。返回**你的 key 以及由它派生的 key**，绝不包含别人的。分页（`{ count, limit, next_page_token?, api_keys }`）。

## 读取一把 key

`GET /v0/api-keys/{api_key_id}`

你的 key，或由它派生的 key；否则 `404 not_found`。

## 创建 key

`POST /v0/api-keys`

**只能由人做**：`403 human_required`。key 在控制台里创建，需要再次验证，并且只显示一次。

## 收紧一把 key

`PATCH /v0/api-keys/{api_key_id}`

你的 key，或由它派生的 key。你只能把 key 变弱：

| 字段 | 允许的改动 |
|---|---|
| `name` | 任意 |
| `permissions` | 当前权限的子集（只能删除） |
| `expires_at` | 早于当前的过期时间 |

任何会放宽 key 的改动都返回 `403 missing_permission`。收紧立即生效，包括已经打开的 WebSocket 连接（以 `4401` 关闭）。

## 吊销一把 key

`DELETE /v0/api-keys/{api_key_id}`

你的 key，或由它派生的 key。吊销立即生效：这把 key 已经排队的发送会在最后一次检查被拦住（`principal_revoked`），它的 WebSocket 连接会关闭。

## 邮箱与 pod 变体

`/v0/inboxes/{inbox_id}/api-keys…` 和 `/v0/pods/{pod_id}/api-keys…` 列出并管理作用域是那个邮箱或 pod 的 key，规则相同。

## key 泄露时

吊销它（`DELETE`，或在控制台里），并向你的主人要一把新的。用 `GET /v0/sends/{send_id}` 和控制台的审计日志检查它发出过什么。