跳到主要内容

发送短信、邮箱验证码

POST 
/auth/v1/verification

接口说明​

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

本接口支持两种模式：

  • 验证码模式（默认）：发送6位数字验证码到用户手机或邮箱，用户需手动输入验证码完成验证。
  • Magic Link 模式：当请求体中传入 email_redirect_to 参数时启用，仅支持邮箱（email 参数），不支持手机号。邮件内容为包含登录链接的按钮，用户点击即可完成登录/注册并跳转到指定页面。

入参要求​

必需参数​

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

可选参数（二选一）​

  • phone_number: 手机号（可选，有效的国内手机号，需加上"+86 "前缀，如"+86 15588665555"）
  • email: 邮箱（可选，有效的邮箱地址，格式如abc@example）
  • email_redirect_to: 跳转URL（可选，string 类型）。登录成功后跳转的目标页面地址。传入此参数即触发 Magic Link 模式，邮件内容从验证码文本变为包含登录链接的按钮邮件。
    • 必须传入完整 URL，如 https://envId-appid.tcloudbaseapp.com/dashboard
    • 仅在传入 email 参数时生效，不支持与 phone_number 搭配使用

请求头参数​

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

前置条件​

  • 需要在云开发平台开启手机号或邮箱登录功能
  • 手机号和邮箱不能同时传入，只能选择其一
  • 当接口返回captcha_required错误时，需要先完成图片验证码验证
  • Magic Link 模式额外要求：email_redirect_to 中的域名需为已配置的自定义域名或 CloudBase 默认域名，否则用户点击链接后可能返回404

出参说明​

验证码模式（未传 email_redirect_to）成功响应​

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

Magic Link 模式下验证码已嵌入邮件链接中，用户无需手动验证，响应中不包含 verification_id 字段。

请求示例​

发送邮箱验证码请求示例（验证码模式）​

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

发送手机号验证码请求示例（验证码模式）​

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

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

{
  "email": "user@example.com",
  "target": "USER"
}
{
  "email": "user@example.com",
  "target": "ANY",
  "email_redirect_to": "https://envId-appid.tcloudbaseapp.com/dashboard"
}

响应示例​

验证码模式 - 发送成功响应示例​

{
  "verification_id": "your_access_token",
  "expires_in": 600,
  "is_user": true
}

Magic Link 模式 - 发送成功响应示例​

{
  "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二选一
email_redirect_tostring否跳转URL。传入此参数触发 Magic Link 模式，邮件将包含登录链接而非验证码。必须传入完整URL。仅与 email 参数搭配使用
x-captcha-tokenstring否图片验证码token，请求头中传入，接口报错captcha_required时必填

响应参数（验证码模式 - 未传 email_redirect_to）​

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

响应参数（Magic Link 模式 - 传入 email_redirect_to）​

字段名类型必填说明
expires_ininteger是过期时间，单位为秒，默认600秒
is_userboolean否用户是否存在，true表示已注册

使用流程​

流程一：验证码模式（默认，未传 email_redirect_to）​

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

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

2. 发送验证码​

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

3. 用户接收验证码​

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

4. 验证验证码​

5. 后续操作​

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

1. 前端调用发送接口​

  • 调用本接口，请求体中传入 email 和 email_redirect_to 参数
  • 后端检测到 email_redirect_to 后自动切换为 Magic Link 模式

2. 用户收到邮件并点击链接​

  • 用户收到包含"确认邮箱并登录"按钮的邮件
  • 点击按钮后自动完成登录/注册，并跳转到 email_redirect_to 指定的目标页面
  • 用户到达目标页面时已处于登录状态，可直接使用应用

关键特性​

验证码特性​

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

安全性​

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

使用场景​

场景一：验证码登录（target=ANY，不传 email_redirect_to）​

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

场景二：找回密码（target=USER，不传 email_redirect_to）​

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

场景三：注册验证（target=ANY，不传 email_redirect_to)​

  • 用户注册新账号
  • 必须是未注册用户
  • 防止重复注册
  • 用户通过邮箱进行一键登录，无需手动输入验证码
  • 邮件中包含登录链接按钮，点击即完成登录并跳转到指定页面
  • 如果用户未注册，点击链接后将自动完成注册并登录
  1. SaaS 应用向用户邮箱发送 Magic Link，email_redirect_to 设为应用的 Dashboard 页面
  2. 用户收到邮件，点击"确认邮箱并登录"按钮
  3. 浏览器自动完成登录，跳转到 Dashboard 页面
// 请求示例
{
  "email": "invitee@company.com",
  "target": "ANY",
  "email_redirect_to": "https://envId-appid.tcloudbaseapp.com/dashboard?from=invite"
}
// 响应示例
{
  "expires_in": 600,
  "is_user": false
}
  1. 内容平台向订阅者发送 Magic Link，email_redirect_to 设为某篇文章页面
  2. 用户在邮箱中收到邮件，点击链接
  3. 自动登录并跳转到文章页面，直接阅读
// 请求示例
{
  "email": "reader@example.com",
  "target": "USER",
  "email_redirect_to": "https://envId-appid.tcloudbaseapp.com/articles/12345"
}

注意事项​

手机号格式​

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

邮箱格式​

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

发送频率限制​

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

图片验证码​

  • 当检测到异常发送行为时要求图片验证码
  • 需要先调用图片验证码接口完成验证
  • 获取captcha_token后在请求头中传入
  • email_redirect_to 仅在传入 email 参数时生效，不支持 phone_number
  • 必须传入完整 URL（如 https://envId-appid.tcloudbaseapp.com/dashboard），不支持相对路径
  • email_redirect_to 中的域名需为已配置的自定义域名或 CloudBase 默认域名，否则用户点击链接时可能返回404
  • Magic Link 有效期与验证码一致，为600秒（10分钟），过期后链接失效
  • 验证码一次性使用，点击链接完成登录后链接即失效，不可重复使用
  • 邮件中的链接强制使用 HTTPS 协议
  • Token 不会出现在 URL 中
  • 登录完成后 URL 中的验证参数会被自动清除

错误处理策略​

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

相关接口​

Request​

Responses​

Response Headers