认证

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

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

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

API key

Authorization: Bearer sk_<prefix>_<secret>

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

作用域

每把 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。见内测门与等候名单。

人：控制台登录

• 邮箱验证码。 输入邮箱、通过人机验证，再输入我们发出的 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。