跳到主要内容

验证短信、邮箱验证码

POST 
/auth/v1/verification/verify

接口说明​

验证码验证接口，用于验证手机号或邮箱收到的验证码是否正确，返回verification_token用于后续登录或注册操作

功能特性​

  • 支持手机号验证码验证
  • 支持邮箱验证码验证
  • 返回verification_token用于后续身份验证流程
  • 验证码有效期为600秒（10分钟）

入参要求​

必需参数​

  • verification_id: 验证码id（必填，从发送短信、邮箱验证码接口的响应中获取）
  • verification_code: 验证码（必填，手机或邮箱收到的验证码）

可选参数​

  • client_id: 应用对应的客户端id（可选，默认为环境id）
  • x-device-id: 设备id（可选，当前登录设备的id）

前置条件​

  • 需要先调用发送短信、邮箱验证码接口获取验证码
  • 验证码必须在有效期内（默认600秒）
  • verification_id必须与发送验证码时返回的id一致

出参说明​

成功响应​

  • verification_token: 验证码token，用于后续登录或注册接口
  • expires_in: 过期时间，默认600秒

请求示例​

验证码验证请求示例​

POST /auth/v1/verification/verify
Content-Type: application/json

{
  "verification_id": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "verification_code": "123456"
}

响应示例​

验证码验证成功响应​

{
  "verification_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "expires_in": 600
}

验证码验证失败响应​

{
  "error": "invalid_verification_code",
  "error_code": 4001,
  "error_description": "验证码错误，请重新输入"
}

使用流程​

1. 发送验证码​

  • 调用发送短信或邮箱验证码接口
  • 获取verification_id和验证码

2. 用户输入验证码​

  • 用户从手机或邮箱获取验证码
  • 在客户端输入验证码

3. 验证验证码​

  • 调用此接口验证验证码
  • 获取verification_token

4. 使用验证token​

  • 使用verification_token调用登录或注册接口

关键特性​

安全性​

  • 验证码有效期短，防止暴力破解
  • verification_id与验证码绑定，防止重放攻击
  • 支持验证码错误次数限制

兼容性​

  • 支持手机号和邮箱验证码
  • 验证码格式为6位数字
  • 国际化支持，支持不同国家手机号格式

错误处理​

  • 验证码错误时提供明确错误信息
  • 验证码过期时提示重新获取
  • 验证码id不存在时提示重新发送验证码

注意事项​

安全建议​

  • 验证码不应在客户端存储
  • 验证码发送频率应有限制
  • 建议实现验证码错误次数限制

使用场景​

  • 登录时验证身份
  • 注册时验证手机号或邮箱
  • 修改敏感信息时二次验证
  • 找回密码时身份验证

相关接口​

Request​

Body

    verification_id 验证码id (string)required

    从发送短信、邮箱验证码接口的响应中获取

    verification_code 验证码 (string)required

    手机或邮箱收到的验证码，过期时间默认为600秒

Responses​

Response Headers
    Schema
      verification_token 验证码token (string)

      在使用手机号+验证码或邮箱+验证码登录时，传入用户名密码登录/auth/v1/signin接口登录

      expires_in 过期时间 (integer)

      默认600秒

    Loading...