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. In this mode the email body is rendered from the email template of the email identity provider: the server injects the one-time login link into the template variable {{.ConfirmationURL}}. Clicking that link completes login/registration and redirects the user to the page specified by email_redirect_to. Therefore this mode must be used together with an email template that contains the {{.ConfirmationURL}} variable. See Magic Link Email Template Configuration for details.

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 login link email rendered from the email template.
  • 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
  • Once provided, the server renders the {{.ConfirmationURL}} variable in the email template. If the template does not contain this variable, the email received by the user will not contain a login link

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 Requirements:
  • The email template of the email identity provider must contain the {{.ConfirmationURL}} variable, otherwise no login link appears in the email. See Magic Link Email Template Configuration
  • 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 Email Template Configuration

Magic Link mode does not send an email with a fixed layout. Instead, it reuses the email template of the email identity provider: when rendering the template, the server writes the generated one-time login link into the template variable {{.ConfirmationURL}}. Therefore you need to configure the template before using Magic Link.

Template Variables

Variable	Applicable Mode	Description
{{.ConfirmationURL}}	Magic Link mode	One-time login link. After the user clicks it, the CloudBase authentication service verifies it and redirects to the page specified by email_redirect_to
{{.VerificationCode}}	Verification code mode	6-digit verification code
{{.Email}}	Both modes	Recipient email address
{{.ExpireMinutes}}	Both modes	Validity period, in minutes
{{.Usage}}	Both modes	Usage description

Template Example

<h1>Confirm Login</h1>
<p>Hi {{.Email}}, please click the button below to sign in:</p>
<p>
  <a
    href="{{.ConfirmationURL}}"
    style="display:inline-block;padding:10px 20px;background:#0052d9;color:#ffffff;text-decoration:none;border-radius:4px;"
  >
    Confirm Email and Login
  </a>
</p>
<p>The link is valid for {{.ExpireMinutes}} minutes and can only be used once.</p>

How to Configure

Go to CloudBase Platform/Authentication/Login Methods and configure the email template in the "Email Verification Code" card.

Note

If the email template does not contain the {{.ConfirmationURL}} variable, this API still returns success, but the email received by the user will not contain a login link and Magic Link login cannot be completed.

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 one-time login link is embedded in the email through the {{.ConfirmationURL}} template variable. 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, and the server renders the one-time login link into the {{.ConfirmationURL}} variable of the email template. 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. Configure the Email Template

• Add the {{.ConfirmationURL}} variable to the email template of the email identity provider. See Magic Link Email Template Configuration
• This is a one-time configuration; afterwards all Magic Link emails are rendered from this template

2. Frontend Calls Send API

• Call this API, include email and email_redirect_to parameters in the request body
• Backend detects email_redirect_to, automatically switches to Magic Link mode, and renders the one-time login link at the {{.ConfirmationURL}} position of the template

3. User Receives Email and Clicks Link

• User receives the email rendered from the template and clicks the login link inside it
• The CloudBase authentication service verifies the one-time credential in the link, 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 is rendered from the configured email template, in which {{.ConfirmationURL}} is the login link; clicking it completes login and redirects to the 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 and clicks the login link rendered from {{.ConfirmationURL}} in the template
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
• The email body is rendered from the email template, which must contain the {{.ConfirmationURL}} variable, otherwise no login link appears in the email
• 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
• Email Template Configuration - Configure the Magic Link email template

Request

Responses

200

Response Headers