API 参考

API key

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

docs.simail.ai/zh/api/api-keys

{
  "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} 和控制台的审计日志检查它发出过什么。