POST/api/v1/auth/register手机号 / 邮箱 + OTP 验证注册账号

Try it 面板需要启用 JavaScript。

先经 otp/send 发码、otp/verify 换取已验证工单，再注册。注册成功不签发会话，需随后登录。

Request

Headers

Name	Data Type	Required	Description
Content-Type	string	Yes	请求体内容类型（默认值 "application/json"）

type RequestHeaders = {
  /** 请求体内容类型，默认值 "application/json" */
  Content-Type: string
}

{
  "Content-Type": "application/json"
}

Body

Name	Data Type	Required	Description
channel	string	Yes	注册通道：phone / email
target	string	Yes	手机号或邮箱
verifyTicket	string	Yes	OTP 已验证工单（scene=register）
username	string	No	用户名（唯一，可选）
password	string	No	登录密码（可选，注册后可经 OTP 登录）

type RequestBody = {
  /** 注册通道：phone / email */
  channel: string
  /** 手机号或邮箱 */
  target: string
  /** OTP 已验证工单（scene=register） */
  verifyTicket: string
  /** 用户名（唯一，可选） */
  username?: string
  /** 登录密码（可选，注册后可经 OTP 登录） */
  password?: string
}

{
  "channel": "email",
  "target": "chen.lin@example.com",
  "verifyTicket": "otv_3d81fa09c2476b5e",
  "username": "chenlin",
  "password": "J8v#pQ2mXs!a"
}

Response

Body

Name	Data Type	Required	Description
userId	string	Yes	新用户 ID
username	string	No	用户名（未提供时为空）
channel	string	Yes	注册通道
target	string	Yes	注册手机号 / 邮箱
createdAt	string	Yes	创建时间

type ResponseBody = {
  /** 新用户 ID */
  userId: string
  /** 用户名（未提供时为空） */
  username?: string
  /** 注册通道 */
  channel: string
  /** 注册手机号 / 邮箱 */
  target: string
  /** 创建时间 */
  createdAt: string
}

{
  "userId": "01JD8SEGQ0P9N2XK4L7VDH3T6C",
  "username": "chenlin",
  "channel": "email",
  "target": "chen.lin@example.com",
  "createdAt": "2026-10-14T08:05:00Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	返回新建用户
409	目标已注册	该手机号 / 邮箱已有账号

Response Code

响应使用统一信封 {id, code, messages, result}，其 code 字段：

code	Meaning	Notes
0	成功	返回新建用户
2009	目标已注册	该手机号 / 邮箱已存在账号
2010	用户名已被占用	指定的 username 已存在
2202	OTP 工单无效	verifyTicket 无效、过期或用途不符

Examples

POST /api/v1/auth/register
Content-Type: application/json

{
  "channel": "email",
  "target": "chen.lin@example.com",
  "verifyTicket": "otv_3d81fa09c2476b5e",
  "username": "chenlin",
  "password": "J8v#pQ2mXs!a"
}

{
  "id": "01JD8SH1K2M8W3XN",
  "code": 0,
  "messages": [],
  "result": {
    "userId": "01JD8SEGQ0P9N2XK4L7VDH3T6C",
    "username": "chenlin",
    "channel": "email",
    "target": "chen.lin@example.com",
    "createdAt": "2026-10-14T08:05:00Z"
  }
}

Remarks

OTP 工单在注册成功时一次性消费；注册失败不消费，可重试。环境指纹随本请求首次记录，但不创建登录尝试。