Skip to main content

Verify SMS, Email Verification Code

POST 
/auth/v1/verification/verify

API Description​

Verification code verification API, used to verify if verification code received by phone or email is correct, returns verification_token for subsequent login or registration operations

Features​

  • Supports phone number verification code verification
  • Supports email verification code verification
  • Returns verification_token for subsequent identity verification flow
  • Verification code valid for 600 seconds (10 minutes)

Input Requirements​

Required Parameters​

  • verification_id: Verification code ID (required, obtained from send SMS, email verification code API response)
  • verification_code: Verification code (required, verification code received by phone or email)

Optional Parameters​

  • client_id: Client ID corresponding to the application (optional, defaults to environment ID)
  • x-device-id: Device ID (optional, current logged-in device ID)

Prerequisites​

  • Need to first call Send SMS, Email Verification Code API to get verification code
  • Verification code must be within validity period (default 600 seconds)
  • verification_id must match the ID returned when sending verification code

Output Description​

Successful Response​

  • verification_token: Verification code token, used for subsequent login or registration API
  • expires_in: Expiration time, default 600 seconds

Request Example​

Verification Code Verification Request Example​

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

{
  "verification_id": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlIjoidG9wc29ud2FuZzE2M0AxNjMuY29tIiwiZXhwIjoxNzQ3OTc0MjUxLCJraWQiOiJmY2JlMzBlZC1mNTc3LTRhMDQtOWIyZi05YTI4ZTc0NjA5MzQiLCJwaiI6Imxvd2NvZGUtNWc5YWMyMHUyYTI3ZGE0NiIsInQiOiJBR055Y0hRT0F3NjN4MUhBIn0",
  "verification_code": "123456"
}

Response Examples​

Verification Code Verification Success Response​

{
  "verification_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE3MzQ2ODIzNTcsInByb2plY3QiOiJsb3djb2RlIiwidHlwZSI6InZlcmlmaWNhdGlvbiJ9",
  "expires_in": 600
}

Verification Code Verification Failure Response​

{
  "error": "invalid_verification_code",
  "error_code": 4001,
  "error_description": "Verification code error, please re-enter"
}

Usage Flow​

1. Send Verification Code​

  • Call send SMS or email verification code API
  • Get verification_id and verification code

2. User Inputs Verification Code​

  • User gets verification code from phone or email
  • Inputs verification code on client

3. Verify Verification Code​

  • Call this API to verify verification code
  • Get verification_token

4. Use Verification Token​

  • Use verification_token to call login or registration API

Key Characteristics​

Security​

  • Short verification code validity period prevents brute-force cracking
  • verification_id bound to verification code prevents replay attacks
  • Support verification code error count limit

Compatibility​

  • Supports phone number and email verification codes
  • Verification code format is 6 digits
  • Internationalization support, supports different country phone number formats

Error Handling​

  • Provide clear error message when verification code is wrong
  • Prompt to get new code when verification code expires
  • Prompt to resend verification code when verification code ID does not exist

Notes​

Security Recommendations​

  • Verification code should not be stored on client
  • Verification code send frequency should be limited
  • Recommend implementing verification code error count limit

Usage Scenarios​

  • Verify identity during login
  • Verify phone number or email during registration
  • Secondary verification when modifying sensitive information
  • Identity verification during password recovery

Request​

Body

    verification_id Verification Code ID (string)required

    Obtained from the response of the Send SMS, Email Verification Code API

    verification_code Verification Code (string)required

    Verification code received by phone or email, expiration time defaults to 600 seconds

Responses​

Response Headers
    Schema
      verification_token Verification code token (string)

      Used to pass to the verify SMS, email verification code /auth/v1/signin interface login when logging in with phone number + verification code or email + verification code

      expires_in Expiration Time (integer)

      default 600 seconds

    Loading...