API Key 与安全
区分凭证、限制发送域名范围，并安全轮换与撤销密钥。
1. 两类 Bearer 凭证
用户会话 Token 管理 domains、api-keys 和 webhooks；API Key 用于 /v1/mail 与 SMTP 密码。API Key 不等于账户密码、会话 Token 或语言 Cookie。GET /v1/apikey/verify 可验证 Key，但不保证域名已验证或套餐有足够额度。
2. 创建并保存
邮箱验证后使用 POST /api-keys，name 为非空字符串，domain_id 为可选数字 ID。完整 key 只在 201 创建响应出现。请存入服务端秘密管理工具，不要记录到日志、截图或前端代码。列表无法找回明文。
| 字段 / 配置 | 类型 / 状态 | 说明 |
|---|---|---|
| name | string | 创建时必填非空 |
| domain_id | uint64 | 创建可选域名 ID |
| key | string | 仅创建时的完整密钥 |
| id / key_prefix / status | uint64 / string | 列表元数据；key_prefix 不能认证 |
| allowed_domain_id / last_used_at | uint64 / time | 可省略的元数据，不是必有 null |
curl -X POST "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}" \
-H "Content-Type: application/json" \
--data '{"name":"Server integration","domain_id":123}'
curl -X GET "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"
curl -X DELETE "${SMTPDOG_API_ORIGIN}/api-keys/${SMTPDOG_KEY_ID}" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"3. 限制发送范围
省略 domain_id 可用于账户所有已验证域名；指定时只允许该域名发送。创建时检查域名归属，发送时仍检查 verified。当前没有 Key 有效期、角色或原地修改范围能力。范围限制不代替域名所有权验证和反滥用检查。
4. 轮换与撤销
轮换流程是创建新 Key、更新自有服务配置、确认切换，再 DELETE /api-keys/{id} 撤销旧 Key。撤销返回 204 无正文；新请求不能再使用该 Key。当前没有原地轮换或找回明文接口。误用会话 Token 时，先检查接口所需认证，而非重复重试。