Send SMS, Email Verification Code

POST 
/auth/v1/verification

API Description

Send SMS or email verification code API, used to send verification code to user's phone number or email, supports multiple scenarios such as login, registration, password recovery.

This API supports two modes:

• Verification Code Mode (Default): Sends a 6-digit verification code to the user's phone or email. The user needs to manually enter the code to complete verification.
• Magic Link Mode: Enabled when the email_redirect_to parameter is included in the request body. Only supports email (email parameter), not phone number. The email contains a login link button. Users can complete login/registration and redirect to the specified page by clicking it.

Input Requirements

Required Parameters

• target: Target for sending verification code (required, optional values: ANY, USER)
  • ANY: No restriction, send regardless of whether user exists
  • USER: Account must exist in system to send

Optional Parameters (Choose One)

• phone_number: Phone number (optional, valid domestic phone number, needs "+86 " prefix, e.g., "+86 15588665555")
• email: Email (optional, valid email address, format abc@xxx)

Magic Link Parameters

• email_redirect_to: Redirect URL (optional, string type). The target page URL to redirect to after successful login. Including this parameter triggers Magic Link mode, changing email content from verification code text to a button with login link.
  • Must provide a full URL, e.g., https://envId-appid.tcloudbaseapp.com/dashboard
  • Only effective when email parameter is provided, does not support use with phone_number

Request Header Parameters

• x-captcha-token: Verification code token (optional, obtained from Verify Image Verification Code API, required when API returns captcha_required error)

Prerequisites

• Need to enable phone number or email login on Cloud Development Platform
• Phone number and email cannot be passed simultaneously, must choose one
• When API returns captcha_required error, need to complete image verification code verification first
• Magic Link Mode Additional Requirement: The domain in email_redirect_to must be a configured custom domain or CloudBase default domain, otherwise users may get a 404 error when clicking the link

Output Description

Verification Code Mode (without email_redirect_to) Successful Response

• verification_id: Verification code ID (required, used for subsequent verification API)
• expires_in: Expiration time (required, in seconds, default 600 seconds)
• is_user: Whether user exists (optional, true means registered, false or empty means not registered)

Magic Link Mode (with email_redirect_to) Successful Response

• expires_in: Expiration time (required, in seconds, default 600 seconds)
• is_user: Whether user exists (optional, true means registered, false or empty means not registered)

In Magic Link mode, the verification code is embedded in the email link, users do not need to manually verify, and the response does not include the verification_id field.

Request Examples

Send Email Verification Code Request Example (Verification Code Mode)

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

Send Phone Number Verification Code Request Example (Verification Code Mode)

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

Send Verification Code to Existing User Request Example (Verification Code Mode)

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

Send Magic Link Email Request Example (Magic Link Mode)

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

Response Examples

Verification Code Mode - Send Success Response Example

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

Magic Link Mode - Send Success Response Example

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

Image Verification Code Required Response Example

{
  "error": "captcha_required",
  "error_code": 4028,
  "error_description": "Need to complete image verification code verification"
}

Phone Number Format Error Response Example

{
  "error": "invalid_phone_number",
  "error_code": 4001,
  "error_description": "Phone number format error, needs +86 prefix"
}

User Not Found Response Example

{
  "error": "user_not_found",
  "error_code": 4004,
  "error_description": "User does not exist"
}

Send Frequency Too High Response Example

{
  "error": "rate_limit_exceeded",
  "error_code": 4029,
  "error_description": "Verification code send frequency too high, please try again in 60 seconds"
}

Field Description

Request Parameters

Field Name	Type	Required	Description
target	string	Yes	Send target, optional values: ANY (no restriction), USER (user must exist)
phone_number	string	No	Phone number, format "+86 phone_number", choose one with email
email	string	No	Email address, choose one with phone_number
email_redirect_to	string	No	Redirect URL. Including this parameter triggers Magic Link mode, email will contain login link instead of verification code. Must provide full URL. Only used with email parameter
x-captcha-token	string	No	Image verification code token, passed in request header, required when API returns captcha_required error

Response Parameters (Verification Code Mode - without email_redirect_to)

Field Name	Type	Required	Description
verification_id	string	Yes	Verification code ID, used for subsequent verification API
expires_in	integer	Yes	Expiration time, in seconds, default 600 seconds
is_user	boolean	No	Whether user exists, true means registered

Response Parameters (Magic Link Mode - with email_redirect_to)

Field Name	Type	Required	Description
expires_in	integer	Yes	Expiration time, in seconds, default 600 seconds
is_user	boolean	No	Whether user exists, true means registered

Usage Flow

Flow 1: Verification Code Mode (Default, without email_redirect_to)

1. Determine if Image Verification Code is Needed

• Can call directly for first send
• If returns captcha_required error, need to complete image verification code verification first

2. Send Verification Code

• Call this API to send verification code
• Choose target parameter based on scenario
• Pass phone number or email

3. User Receives Verification Code

• User receives verification code in phone or email
• Verification code valid for 600 seconds (10 minutes)

4. Verify Verification Code

• Call Verify SMS, Email Verification Code API
• Pass verification_id and user input verification code
• Get verification_token

5. Subsequent Operations

• If is_user is true, use verification_token to call login API
• If is_user is false or empty, use verification_token to call registration API

Flow 2: Magic Link Mode (with email_redirect_to)

1. Frontend Calls Send API

• Call this API, include email and email_redirect_to parameters in the request body
• Backend detects email_redirect_to and automatically switches to Magic Link mode

2. User Receives Email and Clicks Link

• User receives an email with a "Confirm Email and Login" button
• Clicking the button automatically completes login/registration and redirects to the target page specified by email_redirect_to
• User is already logged in when arriving at the target page and can use the application directly

Key Characteristics

Verification Code Characteristics

• Verification code length is 6 digits
• Valid for 600 seconds (10 minutes)
• Same phone number or email can only send once within 60 seconds
• Verification code becomes invalid immediately after use

Security

• Limit send frequency to prevent SMS bombing
• Support image verification code protection
• Record send logs

Usage Scenarios

Scenario 1: Verification Code Login (target=ANY, without email_redirect_to)

• User logs in with phone number or email
• No restriction on whether user exists
• Suitable for login or registration flow

Scenario 2: Password Recovery (target=USER, without email_redirect_to)

• User forgets password
• Must be registered user
• Prevent user information leakage

Scenario 3: Registration Verification (target=ANY, without email_redirect_to)

• User registers new account
• Must be unregistered user
• Prevent duplicate registration

Scenario 4: Magic Link One-Click Login (target=ANY, with email_redirect_to)

• User logs in via email with one click, no need to manually enter verification code
• Email contains a login link button, clicking completes login and redirects to specified page
• If user is not registered, clicking the link will automatically complete registration and login

Magic Link Scenario Example: SaaS Application Invite Login

1. SaaS application sends Magic Link to user's email, email_redirect_to set to application's Dashboard page
2. User receives email, clicks "Confirm Email and Login" button
3. Browser automatically completes login, redirects to Dashboard page

// Request Example
{
  "email": "invitee@company.com",
  "target": "ANY",
  "email_redirect_to": "https://envId-appid.tcloudbaseapp.com/dashboard?from=invite"
}

// Response Example
{
  "expires_in": 600,
  "is_user": false
}

Magic Link Scenario Example: Content Subscription Email with Embedded Login

1. Content platform sends Magic Link to subscriber, email_redirect_to set to an article page
2. User receives email in inbox, clicks the link
3. Automatically logs in and redirects to article page for reading

// Request Example
{
  "email": "reader@example.com",
  "target": "USER",
  "email_redirect_to": "https://envId-appid.tcloudbaseapp.com/articles/12345"
}

Notes

Phone Number Format

• Must add "+86 " prefix
• Format example: "+86 13800138000"
• Does not support other country phone numbers

Email Format

• Must be valid email address
• Format example: "user@example.com"
• Supports common email service providers

Send Frequency Limit

• Same phone number or email can only send once within 60 seconds
• Same IP can send maximum 10 times per hour
• Need to wait after exceeding limit

Image Verification Code

• Require image verification code when abnormal send behavior detected
• Need to call image verification code API to complete verification first
• Pass captcha_token in request header after obtaining

email_redirect_to Parameter Rules (Magic Link Mode)

• email_redirect_to only effective when email parameter is provided, does not support phone_number
• Must provide a full URL (e.g., https://envId-appid.tcloudbaseapp.com/dashboard), relative paths are not supported
• The domain in email_redirect_to must be a configured custom domain or CloudBase default domain, otherwise users may get a 404 error when clicking the link
• Magic Link validity is the same as verification code, 600 seconds (10 minutes), link expires after that
• Verification code is single-use, link becomes invalid after completing login, cannot be reused

Magic Link Security

• Links in email enforce HTTPS protocol
• Token does not appear in URL
• Verification parameters in URL are automatically cleared after login is complete

Error Handling Strategy

• Friendly error messages
• Auto handle image verification code flow
• Implement send countdown
• Record error logs

Related APIs

• Verify SMS, Email Verification Code - Verify verification code
• Verify Image Verification Code - Get captcha_token
• Get Image Verification Code - Get image verification code
• User Login - Use verification_token to login
• User Registration - Use verification_token to register

Request

Header Parameters

x-captcha-token string

Verification code token, obtained from the image verification code interface, needs to be passed when the interface reports captcha_required

application/json

Body

phone_number Phone Number (string)

Valid domestic phone number, needs to be prefixed with "+86 ", e.g., "+86 15588665555"

email Email (string)

Valid email, format abc@xxx

target Target for sending verification code (string)required

Pass ANY, other optional values are USER (account must exist in the system)

email_redirect_to Redirect URL (string)

The target URL to redirect to after successful login. Including this parameter triggers Magic Link mode, email will contain login link instead of verification code text. Must provide a full URL (e.g., https://envId-appid.tcloudbaseapp.com/dashboard), relative paths are not supported. Only used with email parameter, does not support phone_number

Responses

200

Response Headers

application/json

Schema

Schema

verification_id Verification Code ID (string)

Used to pass to the verify SMS, email verification code /auth/v1/verification/verify interface for verification code verification

expires_in Verification code expiration time, in seconds (integer)
is_user User Exists (boolean)

Determine whether this phone number or email has been registered as a user, returns true if registered

Example (from schema)

{
  "verification_id": "string",
  "expires_in": 0,
  "is_user": true
}

Example

{
  "verification_id": "your_verification_id",
  "expires_in": 600
}

Loading...