跳到主要内容

发送短信、邮箱验证码

POST 
/auth/v1/verification

接口说明​

发送短信或邮箱验证码接口，用于向用户的手机号或邮箱发送验证码，支持登录、注册、找回密码等多种场景。

入参要求​

必需参数​

  • target: 发送验证码的目标（必填，可选值：ANY、USER）
    • ANY: 不限制，无论用户是否存在都发送
    • USER: 账号必须在系统中存在才发送

可选参数（二选一）​

  • phone_number: 手机号（可选，有效的国内手机号，需加上"+86 "前缀，如"+86 15588665555"）
  • email: 邮箱（可选，有效的邮箱地址，格式如abc@example）

请求头参数​

  • x-captcha-token: 验证码token（可选，从验证图片验证码接口获取，接口报错captcha_required时需传入）

前置条件​

  • 需要在云开发平台开启手机号或邮箱登录功能
  • 邮箱登录需配置好SMTP服务器
  • 手机号和邮箱不能同时传入，只能选择其一
  • 当接口返回captcha_required错误时，需要先完成图片验证码验证

出参说明​

成功响应​

  • verification_id: 验证码id（必填，用于后续验证接口）
  • expires_in: 过期时间（必填，单位为秒，默认600秒）
  • is_user: 用户是否存在（可选，true表示已注册，false或空表示未注册）

请求示例​

发送邮箱验证码请求示例​

{
  "email": "user@example",
  "target": "ANY"
}

发送手机号验证码请求示例​

{
  "phone_number": "+86 13800138000",
  "target": "ANY"
}

发送验证码给已存在用户请求示例​

{
  "email": "user@example",
  "target": "USER"
}

响应示例​

发送成功响应示例​

{
  "verification_id": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "expires_in": 600,
  "is_user": true
}

需要图片验证码响应示例​

{
  "error": "captcha_required",
  "error_code": 4028,
  "error_description": "需要完成图片验证码验证"
}

手机号格式错误响应示例​

{
  "error": "invalid_phone_number",
  "error_code": 4001,
  "error_description": "手机号格式错误，需加上+86前缀"
}

用户不存在响应示例​

{
  "error": "user_not_found",
  "error_code": 4004,
  "error_description": "用户不存在"
}

发送频率过高响应示例​

{
  "error": "rate_limit_exceeded",
  "error_code": 4029,
  "error_description": "发送验证码频率过高，请60秒后重试"
}

字段说明​

请求参数​

字段名类型必填说明
targetstring是发送目标，可选值：ANY（不限制）、USER（用户必须存在）
phone_numberstring否手机号，格式为"+86 手机号"，与email二选一
emailstring否邮箱地址，与phone_number二选一
x-captcha-tokenstring否图片验证码token，请求头中传入，接口报错captcha_required时必填

响应参数​

字段名类型必填说明
verification_idstring是验证码id，用于后续验证接口
expires_ininteger是过期时间，单位为秒，默认600秒
is_userboolean否用户是否存在，true表示已注册

使用流程​

1. 判断是否需要图片验证码​

  • 首次发送可直接调用
  • 如果返回captcha_required错误，需要先完成图片验证码验证

2. 发送验证码​

  • 调用本接口发送验证码
  • 根据场景选择target参数
  • 传入手机号或邮箱

3. 用户接收验证码​

  • 用户在手机或邮箱中接收验证码
  • 验证码有效期为600秒（10分钟）

4. 验证验证码​

5. 后续操作​

  • 如果is_user为true，使用verification_token调用登录接口
  • 如果is_user为false或空，使用verification_token调用注册接口

关键特性​

验证码特性​

  • 验证码长度为6位数字
  • 有效期为600秒（10分钟）
  • 同一手机号或邮箱60秒内只能发送一次
  • 验证码使用后立即失效

安全性​

  • 限制发送频率，防止短信轰炸
  • 支持图片验证码防护
  • 记录发送日志

使用场景​

登录场景（target=ANY）​

  • 用户使用手机号或邮箱登录
  • 不限制用户是否存在
  • 适用于登录或注册流程

找回密码场景（target=USER）​

  • 用户忘记密码
  • 必须是已注册用户
  • 防止泄露用户信息

注册场景（target=ANY)​

  • 用户注册新账号
  • 必须是未注册用户
  • 防止重复注册

注意事项​

手机号格式​

  • 必须加上"+86 "前缀
  • 格式示例："+86 13800138000"
  • 不支持其他国家手机号

邮箱格式​

  • 必须是有效的邮箱地址
  • 格式示例："user@example"
  • 支持常见邮箱服务商

发送频率限制​

  • 同一手机号或邮箱60秒内只能发送一次
  • 同一IP每小时最多发送10次
  • 超过限制需等待后重试

图片验证码​

  • 当检测到异常发送行为时要求图片验证码
  • 需要先调用图片验证码接口完成验证
  • 获取captcha_token后在请求头中传入

错误处理策略​

  • 友好的错误提示信息
  • 自动处理图片验证码流程
  • 实现发送倒计时
  • 记录错误日志

相关接口​

Request​

Header Parameters

    x-captcha-token string

    验证码token，从验证图片验证码接口获取，接口报错captcha_required时需传入

Body

    phone_number 手机号 (string)

    有效的国内手机号，需加上"+86 "前缀，如"+86 15588665555"

    email 邮箱 (string)

    有效的邮箱，格式abc@xxx

    target 发送验证码的目标 (string)required

    传入ANY，其余可选值USER(账号必须在系统中存在)

Responses​

Response Headers
    Schema
      verification_id 验证码id (string)

      用于传入验证短信、邮箱验证码/auth/v1/verification/verify接口进行验证码的验证

      expires_in 验证码过期时间，单位为秒 (integer)
      is_user 用户是否存在 (boolean)

      判断这个手机号或邮箱是否已经注册为用户，已注册返回true

    Loading...