TaskPilots Mailbox Integration Documentation main http-api/token-management.md

title: Mailbox HTTP API Token 自助治理

Mailbox HTTP API Token 自助治理

如果当前 mailbox token 具备 TokenManage，可以自助管理该邮箱自己的后续 tokens。

可用接口

  • GET /api/mailbox/access-tokens
  • POST /api/mailbox/access-tokens
  • POST /api/mailbox/access-tokens/{tokenId}/reveal
  • POST /api/mailbox/access-tokens/{tokenId}/disable
  • DELETE /api/mailbox/access-tokens/{tokenId}

适用范围

只适用于：

  • mailbox token

不适用于：

  • domain token

创建新 token

curl -X POST https://mailbox.feinian.net/api/mailbox/access-tokens \
  -H "Authorization: Bearer <token-with-TokenManage>" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenName": "smtp-client",
    "scopes": ["MailboxSend"],
    "expiresAtTs": 1780000000000
  }'

规则：

  • tokenName 必填
  • scopes 至少一个
  • 新 token 的 scopes 必须是当前 token scopes 的子集
  • 新 token 的过期时间不能晚于当前 token

reveal 的语义

POST /api/mailbox/access-tokens/{tokenId}/reveal 用于查看仍可显示明文的 token。

注意：

  • 成功返回明文 token 时，响应会带 Cache-Control: no-store
  • 如果历史 token 的明文已不可用，可能返回 409 Conflict

disable 与 delete 的区别

disable

  • 停用该 token
  • 之后不能继续使用

delete

  • 删除该 token 记录
  • 适合不再保留的 token

常见失败

400 Bad Request

常见原因：

  • 请求了超出当前权限的 scopes
  • expiresAtTs 非法

403 Forbidden

常见原因：

  • 当前 token 不是 mailbox token
  • 当前 token 不具备 TokenManage

404 Not Found

常见原因：

  • tokenId 不存在
  • 当前邮箱无权管理该 token

409 Conflict

常见原因：

  • 请求 reveal 时，该 token 明文已不可再次显示

推荐做法

  • HTTP API、SMTP、自动化程序分别使用不同 token
  • 给 SMTP token 只授予 MailboxSend
  • 定期轮换 token
  • 历史 token 明文如果没有保存，不要依赖未来一定能再次 reveal