v1auth 上下文凭据管理
邮箱凭据
追加邮箱、确认、重发验证码与设为主邮箱。
邮箱是最基础的登录与接收地址。一个账号可以绑定多个邮箱，但只有主邮箱决定「验证码发到哪」「重置链接发到哪」。
端点
| 方法 | 路径 | 说明 | 提权 |
|---|---|---|---|
POST | /v1/auth/credentials/email/options | 向新地址发送验证码 | max_age=300 |
POST | /v1/auth/credentials/email | 提交验证码完成绑定 | 无 |
POST | /v1/auth/credentials/email/resend | 重发验证码 | 无 |
POST | /v1/auth/credentials/email/:credentialId/primary | 设为主邮箱 | max_age=300 |
第一步：发送验证码
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
email | string | ✅ | 待绑定地址，3–254 字符 |
{ "success": true, "expires_in": 600, "resend_after": 60 }地址被钉在服务端状态里，有效期 10 分钟。resend_after 是「距下次可重发还有多少秒」，由服务端计算，客户端不要自己数秒——冷却键在发信成功后才落下，界面自算会与服务端剩余时间错开。
第二步：确认绑定
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | string | ✅ | 收到的验证码，4–32 字符 |
{ "success": true, "credential": { "id": "cred_...", "type": "email" } }这一步不接受邮箱地址
地址已在第一步钉进服务端状态，这里再收一次就会出现「发的码是 A、绑的是 B」这种组合。 账号的第一个邮箱会自动成为主邮箱。
重发验证码
无请求体，返回与第一步相同的形状。只要求普通会话：验证码有效期 600 秒，而第一步的提权窗口只有 300 秒，若这里也要求提权，等到超时再点重发的用户会被弹去重新登录。
重复调用在冷却窗口内会被拒，响应带 Retry-After。
设为主邮箱
{ "success": true, "credentials": [ { "id": "cred_...", "primary": true } ] }返回整组邮箱而不是单条：主次是行与行之间的相对关系，只回一行的话前端还得自己推断哪一行被降级了。
主邮箱不能直接删除，因此本端点是移动这个锚点的唯一途径。每次调用都会写入安全记录。