# 认证

Source: https://docs.simail.ai/zh/authentication/

> agent 用 API key、作用域和权限；人用邮箱验证码、passkey 和再次验证。

simail 有两类主体，它们从不共用凭据：

- **agent** 用 **API key** 调用 `api.simail.ai`（REST、MCP、WebSocket）。
- **人**使用控制台 `app.simail.ai`，用**邮箱验证码**或 **passkey** 登录。

有些操作只留给人，通过 API 调用会返回 `403 human_required`：建 API key、建或改 webhook、放宽允许/拦截名单、放行被扣留的信、审批发信。

## API key

```http
Authorization: Bearer sk_<prefix>_<secret>
```

- key 只在人创建时显示一次。simail 只保存带密钥的哈希。
- 缺失、格式错误、过期或已吊销的 key 返回 `401 unauthorized`。
- 把 key 放在环境变量或密钥管理器里。永远不要把 key 贴进提示词、邮件或共享文件。`simail` 命令行只从 `SIMAIL_API_KEY` 读取 key。
- `GET /v0/auth/me` 告诉你正在用哪把 key、它的作用域、权限，以及是否已 `claimed`（见[身份与组织](/zh/api/identity/)）。
- `GET /v0/api-keys` 列出你的 key 以及由它派生的 key。一把 key 可以给自己改名、删权限、提前过期（`PATCH`），或吊销自己（`DELETE`），但永远不能增加权限。见 [API key](/zh/api/api-keys/)。

### 作用域

每把 key 绑定且只绑定一个作用域：

| 作用域 | 能看到 |
|---|---|
| `org` | 组织内的所有邮箱（平台运维邮箱除外） |
| `pod` | 一个 pod（一组邮箱）里的邮箱 |
| `inbox` | 一个邮箱 |

组织级接口（如 `GET /v0/threads`）会收窄到你作用域内的邮箱。作用域之外的一切，包括其他组织，都返回 **`404 not_found`**，所以 key 无法探知某个对象是否存在。对象在作用域内但 key 缺少相应权限时，返回 `403 missing_permission`。

### 权限

| 权限 | 允许 |
|---|---|
| `inbox_read` | 列出和读取邮箱与 pod |
| `inbox_create` | 建邮箱（组织级和 pod 级 key） |
| `inbox_update` | 修改邮箱设置 |
| `inbox_delete` | 删除邮箱（地址退役，永不重新分配） |
| `message_read` | 读线程、消息、草稿、附件、发送状态 |
| `message_raw_read` | 读原始 `.eml` 和 `html` 字段（默认不授予 agent key） |
| `message_send` | 发信、回复、回复全部、转发、发送草稿、取消定时发送 |
| `message_update` | 加或删标签 |
| `message_delete` | 把消息和线程移入回收站 |
| `draft_write` | 建、改、删草稿 |
| `label_spam_read` | 列表中包含 `spam` |
| `label_blocked_read` | 列表中包含 `blocked` |
| `label_trash_read` | 列表中包含 `trash` |
| `hold_metadata_read` | 在列表中看到被扣留邮件的元数据 |
| `list_read` | 读允许/拦截名单 |
| `list_tighten` | 加拦截条目或删允许条目（永远不能放宽） |
| `webhook_read` | 读 webhook 配置和投递记录 |
| `event_read` | `GET /v0/events`、邮箱事件和 WebSocket 推送 |
| `usage_read` | 用量、配额和指标 |
| `approval_read` | 读审批状态（仅元数据） |

控制台给 agent key 的默认预设是 `inbox_read`、`message_read`、`draft_write`、`message_send`、`message_update`、`list_read`、`list_tighten`、`event_read`、`usage_read`、`approval_read`。不包含原文读取、删除，以及 spam/blocked/trash 标签。

**key 只能收紧。** 派生 key 的作用域、权限和有效期永远在父 key 之内。没有任何权限能让 key 放行被扣留的信、批准发信、建 key、建 webhook 或放宽名单。

### 认领前的受限 key

`POST /v0/agent/sign-up` 返回的 key 在人认领这个 agent 之前是受限的：只能调用 `GET /v0/auth/me` 和 `GET /v0/beta`，其余请求一律返回 `403 claim_required`。认领时会轮换 key。见[内测门与等候名单](/zh/beta/)。

## 人：控制台登录

- **邮箱验证码。** 输入邮箱、通过人机验证，再输入我们发出的 6 位验证码。验证码 10 分钟内有效，可尝试 3 次。失败次数过多会把该邮箱的验证码登录锁定一小时；任何响应都不会透露某个邮箱是否已注册。
- **passkey。** 首次登录后，可以添加 passkey 并直接用它登录。添加或删除 passkey 都必须先完成一次**新的邮箱验证码**，并且我们会发邮件通知你，邮件里有"不是我本人"的链接，可一键吊销该 passkey 和全部会话。
- **再次验证（step-up）。** 敏感操作（key、webhook、放宽名单、策略、审批、放行扣留邮件、导出、删除组织、认领 agent、生成 agent 定向码、连接 Telegram 或 Slack、MCP OAuth 授权）要求 5 分钟内完成过一次 passkey 断言或新的邮箱验证码。添加不满 24 小时的 passkey 不能用于再次验证。
- 会话有效期 7 天，使用 `__Host-` cookie（HttpOnly、Secure、SameSite=Strict），退出即失效。

## MCP 认证

MCP 使用同样的 API key（`Authorization: Bearer …`）。支持 MCP OAuth 的客户端也可以不带 key 连接：由你在控制台批准这次连接，选好邮箱和权限（只能比你自己的更窄），simail 为该客户端生成一把限定作用域的 key。在控制台吊销这把 key，客户端就断开了。见 [MCP](/zh/mcp/)。