Skip to main content

Get Image Verification Code

POST 
/auth/v1/captcha/data

API Description​

Get image verification code API, returns RFC 2397 standard inline image data URI for human-machine verification in login, registration and other scenarios.

Input Requirements​

Request Parameters​

  • No parameters required, call directly

Prerequisites​

  • No special prerequisites
  • Recommend calling when user login fails too many times
  • Can be used in sensitive operations such as registration, password recovery

Output Description​

Successful Response​

  • data: Image data (required, RFC 2397 standard inline image data URI, format data:image/gif;base64,xxx)
  • type: Resource type (required, fixed value "image")
  • token: Verification code token (required, used for subsequent verification API)
  • expires_in: Expiration time (required, in seconds, default 300 seconds)

Request Example​

Get Image Verification Code Request Example​

POST /auth/v1/captcha/data
Content-Type: application/json

{}

Response Example​

Successful Response Example​

{
  "data": "data:image/gif;base64,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",
  "type": "image",
  "token": "aC_raGNycHQOSR7w0V7U0Ble-edJud_-AJofUvLFga8v59WsZVRI_RUBxC9Tk5eUoBNrdPhqA0M_ZkT0V0le909Z7YmWHVT4Yead026_",
  "expires_in": 300
}

Field Description​

Response Parameters​

Field NameTypeRequiredDescription
datastringYesImage data, RFC 2397 standard inline image data URI, includes protocol header (data:), MIME type (image/gif), encoding method (base64) and actual data
typestringYesResource type, fixed value "image"
tokenstringYesVerification code token, used for subsequent verification API
expires_inintegerYesExpiration time, in seconds, default 300 seconds

Usage Flow​

1. Get Verification Code Image​

  • Frontend calls this API to get verification code data
  • Assign data field directly to img tag's src attribute
  • Save token properly for subsequent verification
  • Implement refresh verification code function

2. User Inputs Verification Code​

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

3. Submit Verification Code Verification​

4. Business API Authorization​

  • Attach request header in business requests requiring verification code protection
  • Request header format: x-captcha-token: xxx

Key Characteristics​

Image Format​

  • Conforms to RFC 2397 standard Data URI
  • Uses GIF format
  • Base64 encoding
  • Can be used directly in HTML

Security​

  • Verification code token valid for 300 seconds
  • New verification code generated each time
  • Verification code becomes invalid after use
  • Supports anti-brute-force mechanism

Usage Scenarios​

Login Protection​

  • Require verification code when user login fails too many times
  • Prevent brute-force password cracking
  • Protect account security

Registration Protection​

  • Prevent batch registration
  • Prevent malicious registration
  • Protect system resources

Sensitive Operation Protection​

  • Password recovery
  • Password modification
  • Binding information modification
  • Account deletion

Notes​

Frontend Implementation​

  • Assign data field directly to img tag's src attribute
  • Save token properly for subsequent verification
  • Implement refresh verification code function
  • Need to get new code after expiration

Security Recommendations​

  • Verification code should be generated on server-side
  • Verification code content should be random and unpredictable
  • Limit acquisition frequency for same IP
  • Record verification code acquisition logs

Common Errors​

  • Server error: Retry acquisition
  • Network timeout: Check network connection
  • Rate limit: Wait and retry

Error Response Example​

{
  "error": "rate_limit_exceeded",
  "error_code": 4029,
  "error_description": "Verification code acquisition frequency too high, please try again later"
}

Request​

Responses​

Response Headers
    Schema
      data Image Data (string)required

      RFC 2397 standard inline image data URI, including the following parts: protocol header: data: MIME type: image/gif encoding method: base64 actual data: Base64 encoded binary data conforming to RFC 4648

      type Type (string)required

      Enumerated value of resource type: "image" for image resources. Other values are reserved for future expansion.

      token Token (string)required

      The token to be passed to the verification code verification API

      expires_in Expiration Time (integer)required

      Token expiration time, default 300 seconds

    Loading...