Skip to main content

Verify Image Verification Code

POST 
/auth/v1/captcha/data/verify

API Description​

Verify image verification code API, used to verify if user input verification code is correct. Returns captcha_token after successful verification for subsequent business API human-machine verification.

Input Requirements​

Required Parameters​

  • token: Verification code token (required, obtained from Get Image Verification Code API)
  • key: Verification code content (required, verification code text input by user after recognizing image)

Prerequisites​

  • Must first call Get Image Verification Code API to get verification code
  • Token not expired (default validity 300 seconds)
  • Verification code not used

Output Description​

Successful Response​

  • captcha_token: Verification code token (required, used for subsequent business API human-machine verification)
  • expires_in: Expiration time (required, in seconds, default 300 seconds)

Request Example​

Verify Image Verification Code Request Example​

{
  "token": "aC_raGNycHQOSR7w0V7U0Ble-edJud_-AJofUvLFga8v59WsZVRI_RUBxC9Tk5eUoBNrdPhqA0M_ZkT0V0le909Z7YmWHVT4Yead026_",
  "key": "AB12"
}

Response Examples​

Verification Success Response Example​

{
  "captcha_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbSIsInN1YiI6Ijk4NzY1NDMyMTAxMjM0NTY3ODkiLCJhdWQiOiJkZW1vLWFwcC0yZjhhOWMzZTFiNGQiLCJleHAiOjE3MzQ2NzU4ODksImlhdCI6MTczNDY2ODY4OSwic2NvcGUiOiJ1c2VyIn0.dGhpc19pc19hX2Zha2Vfc2lnbmF0dXJlX2Zvcl9leGFtcGxlX3B1cnBvc2VzX29ubHlfZG9fbm90X3VzZV9pbl9wcm9kdWN0aW9uX2Vudmlyb25tZW50X3RoaXNfaXNfbm90X3JlYWxfdG9rZW5fZGF0YQ",
  "expires_in": 300
}

Verification Failure Response Example​

{
  "error": "invalid_captcha",
  "error_code": 4001,
  "error_description": "Verification code error"
}

Verification Code Expired Response Example​

{
  "error": "captcha_expired",
  "error_code": 4002,
  "error_description": "Verification code expired, please get new one"
}

Verification Code Already Used Response Example​

{
  "error": "captcha_used",
  "error_code": 4003,
  "error_description": "Verification code already used, please get new one"
}

Field Description​

Request Parameters​

Field NameTypeRequiredDescription
tokenstringYesVerification code token, obtained from /auth/v1/captcha/data API
keystringYesVerification code text input by user after recognizing image, case-insensitive

Response Parameters​

Field NameTypeRequiredDescription
captcha_tokenstringYesVerification code token, used for subsequent business API human-machine verification
expires_inintegerYesExpiration time, in seconds, default 300 seconds

Usage Flow​

1. Get Verification Code​

2. User Inputs Verification Code​

  • User recognizes verification code in image
  • Inputs verification code in input box

3. Verify Verification Code​

  • Call this API to verify user input
  • Pass token and user input key
  • Get captcha_token

4. Use captcha_token​

  • In business APIs requiring verification code protection
  • Add request header: x-captcha-token: xxx
  • Complete human-machine verification

Key Characteristics​

Verification Rules​

  • Case-insensitive
  • Verification code length 4-6 characters
  • Supports numbers and letters
  • Verification failure does not affect token validity

Security​

  • Verification code becomes invalid immediately after use
  • Limit verification failure attempts
  • Prevent brute-force cracking
  • Record verification logs

Usage Scenarios​

Login Protection​

  • Require verification code when login fails too many times
  • Allow login after verification passes
  • Prevent brute-force cracking

Registration Protection​

  • Require verification code during registration
  • Prevent batch registration
  • Protect system resources

Sensitive Operation Protection​

  • Verify during password recovery
  • Verify during password modification
  • Verify during binding information modification
  • Verify during account deletion

Notes​

Verification Code Input​

  • Case-insensitive
  • Trim leading/trailing spaces
  • Can retry on verification failure
  • Need to get new code after expiration

Error Handling Strategy​

  • Verification code error: Allow retry, get new code after exceeding attempts
  • Verification code expired: Auto refresh verification code
  • Verification code already used: Auto refresh verification code
  • Network error: Retry mechanism

Request​

Body

    token Verification code verification token (string)required

    Obtained from the /auth/v1/captcha/data interface

    key Text content identified in the verification code (string)required

Responses​

Response Headers
    Schema
      captcha_token Verification code token (string)required
      expires_in Expiration Time, default 600 seconds (integer)required
    Loading...