v1auth 上下文
登录与注册
POST /v1/auth/login 与 POST /v1/auth/register：起点参数、流程令牌与可用验证方式。
登录与注册共用同一个形状：提交标识与设备号，换一枚流程令牌（JWE），再逐个完成验证挑战。两者的差别只在于验证方式的来源——登录比对已有凭据，注册把新凭据暂存在流程令牌里。
端点
| 方法 | 路径 | 说明 |
|---|---|---|
POST | /v1/auth/login | 发起登录 |
POST | /v1/auth/register | 发起注册 |
两个端点都必须携带 Cloudflare Turnstile 令牌。它是这里唯一挡批量脚本的手段，缺失或校验失败直接拒绝。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | string | ✅ | 用户名或邮箱，3–255 字符；服务端会去空白并转小写 |
did | string | ✅ | 设备标识，8–256 字符；第一方会话按设备维度记账 |
turnstile | string | ✅ | Turnstile 校验令牌 |
{
"id": "[email protected]",
"did": "device-8f3a1c2b",
"turnstile": "0.xxxxx"
}响应
{
"success": true,
"flow_token": "eyJhbGciOi...",
"available_methods": [
{ "type": "email", "masked": "a***@example.com", "remaining": 1 },
{ "type": "passkey", "remaining": 1 }
]
}| 字段 | 说明 |
|---|---|
flow_token | 流程令牌（JWE）。后续每一次验证请求都把它放在 Authorization: Bearer 里，服务端会换发新的一枚 |
available_methods[].type | email / password / passkey / authenticator / recovery_code |
available_methods[].masked | 打码后的联系方式；仅 email 类出现 |
available_methods[].remaining | 该方式剩余可用次数 |
注册时 available_methods 可能是空数组
新账号还没有任何已验证凭据，因此注册的响应里这个字段可以为空。空数组表示「暂时没有可用的验证方式」，不是注册失败。
后续流程
- 用
flow_token调用 验证挑战 中对应端点； - 每一步成功后都会换回一枚新的
flow_token，必须用新的那枚继续，旧的不再生效； - 全部必需步骤完成后，调用 令牌 的
POST /token，用最后一枚flow_token换取访问令牌与刷新令牌。
静默失败
登录时若请求的邮箱与流程令牌里记录的可用方式不匹配，服务端不会报错，而是「成功返回但不发信」。这是刻意的：报错会告诉调用方「这个账号没绑这个邮箱」，等于把账号结构泄露出去。