身份验证

API 密钥（推荐用于集成）

API 密钥是与您账户中某位成员绑定的个人访问令牌。

在 设置 → 插件 → RolChat API 密钥 中创建。密钥只显示一次；之后只能看到前十个字符，RolChat 只存储其 SHA-256 哈希。
格式：rcp_ 后接 base64url 编码的 32 个随机字节，总共约 45 个字符。该前缀使密钥在日志中易于识别，并与会话令牌区分开。
**作用域：**创建密钥时从固定的能力目录中选择。密钥的权限永远不会超过创建它的成员：每次调用都会同时检查两个条件，即该能力在密钥的作用域中，并且该成员仍然拥有该能力。缩小成员的角色，密钥的权限也会随之缩小。
**有效期：**密钥不会自行过期。可以在个人资料页面或通过 DELETE /api/v1/tokens/:id 撤销密钥；撤销立即生效。不支持就地轮换：请先撤销再创建新密钥。
创建和撤销都会写入审计日志。

以持有者令牌的形式发送，没有单独的 API 密钥标头：

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

使用插件 API 密钥的请求限制为每分钟 300 次。

JWT 会话

网页应用和移动 SDK 使用电子邮件和密码（或 Google、Apple）登录，并获得一对令牌。

令牌	有效期	说明
访问令牌	15 分钟	RS256，根据 `/.well-known/jwks.json` 中的 JWKS 验证
刷新令牌	30 天	每次刷新时轮换；重复使用已轮换的令牌会撤销整个令牌链

声明：sub（用户）、acc（账户）、rl（角色），对于站点级角色还有 sts（允许的站点）。

POST /auth/login、/auth/refresh、/auth/swap-company 和 /auth/logout 是唯一不得携带下文所述 X-Account-Id 标头的认证流程端点。

`X-Account-Id` 标头

除上述四个端点外，每个经过身份验证的请求都必须携带其操作的账户：

X-Account-Id: <account uuid>

服务器会检查该标头是否等于令牌的 acc 声明（或 API 密钥所属的账户）。缺少标头返回 400 missing_required_header；不匹配返回 403 account_context_mismatch。设置该标头是为了让客户端缺陷或被重放的令牌永远无法悄悄读取其他租户的数据：不匹配会在任何查询运行之前被拒绝，并且无需解码令牌即可将每一行日志归属到某个账户。

多公司用户

一个人可以属于多家公司。每家公司都有自己的令牌（自己的 acc 声明）。要切换：

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

目标必须是调用者的 available_companies（登录时返回）之一，否则返回 403 forbidden。响应是一对限定于目标公司的新访问令牌和刷新令牌；旧的刷新令牌会被撤销，并写入一条 auth.account.swapped 审计事件。

多重身份验证

基于 TOTP 的 MFA 可以按成员注册，并按账户要求启用。启用后，POST /auth/login 会返回一个质询，会话通过 POST /auth/mfa/verify 完成。注册时会发放备用码。

登录保护

登录路由限制为每个 IP 每分钟 10 次、每个电子邮件每 15 分钟 5 次。
登录失败十次会将该电子邮件锁定 30 分钟；响应中带有 code: account_locked。
可以按操作（注册、登录、密码重置）启用 reCAPTCHA；公开的引导配置由 GET /api/v1/captcha 提供。