Server Access Documentation
Product Communication Process
Normal Process
When the verification service is functioning normally and the user's network loads properly, the verification code process proceeds. The server needs to focus on the secondary verification phase.

Exception Process
Offline Process Built into the Verification Code
When the verification service is abnormal and the offline mode built into the verification code is used, the server needs to focus on the secondary verification phase. In this case, the server's request to the verification code service will encounter an exception. It is recommended to capture the exception and determine whether to allow the user to proceed based on the business scenario.

Custom Downgrade Process (For Reference Only)
When the verification service is abnormal and a custom downgrade verification, such as character verification, is used, it is recommended that the server add an interface or switch for the frontend to determine the specific verification method. The server can use the check_status interface provided by the verification code to determine whether the verification code is functioning normally.

Server Verification Code Integration Plan
Pre-integration Preparations
Please obtain the necessary resources from the integration client side. Information such as domain addresses should be obtained from the internal company contact after deployment is complete.
| Client Type | Required Resources | Resource Description | Server | captchaId | Verification scenario ID, can be created via the management console |
| captchaKey | Verification scenario KEY, generated when creating a new scenario in the management console, corresponds one-to-one with captchaId |
Server Integration
After the user completes the verification on the frontend interface, a batch of parameters related to the verification code will be generated. The user's business request carries these parameters, and the backend business interface uploads these parameters to the EngageLab secondary verification interface to confirm the validity of the user's verification.
Taking the login scenario as an example:
- Before integrating the verification code, the frontend carries the username and password to request the business login interface. The business side determines whether the username and password match. If they match, login is successful; if not, login is denied.
- After integrating the verification code, the frontend carries business information and verification code-related parameters to request the business login interface. The business side carries the verification code-related parameters to request the verification code server's secondary verification (validate) interface to obtain the verification result. Based on the verification result and the username and password matching result, it determines whether to allow the user to proceed with subsequent business processes.
validate Interface Description
| Interface Information | Description |
|---|---|
| Interface Address | https://captcha-api.engagelab.com/validate |
| Request Method | POST |
| Request Format | application/json |
| Response Type | json |
Request Parameters
| Parameter Name | Type | Description | Source |
|---|---|---|---|
| lot_number | string | Server verification serial number | Passed from the frontend |
| captcha_output | string | Verification output information | Passed from the frontend |
| pass_token | string | Verification pass token | Passed from the frontend |
| gen_time | string | Verification pass timestamp | Passed from the frontend |
| captcha_id | string | Verification scenario ID | Business configuration file, should match the captchaId used by the frontend |
| sign_token | string | Verification signature | Generated by the business side |
The sign_token is generated as follows:
Use the user's current verification serial number lot_number as the original message, use the customer's verification private key captchaKey as the key, and use the hmac_sha256 hash algorithm to hash the message and key in one direction to generate the final signature.
An example in Java code is as follows:
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
Request Body Example
{
"lot_number": "f26d13345c9980c7705b9111b9398a0f",
"captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
"sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
"pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
"gen_time": "1684826917",
"captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}
Response Parameters
| Parameter Name | Type | Required | Example | Description |
|---|---|---|---|---|
| status | String | Yes | success | Interface response status, success indicates a successful response |
| data | Object | Yes | See data field description | Returned field when the interface responds successfully |
The data field is described as follows:
| Parameter Name | Type | Required | Example | Description |
|---|---|---|---|---|
| result | String | Yes | success | Secondary verification result, success indicates verification passed, other values indicate verification failed |
| reason | String | Yes | "" | Verification result description |
| captcha_args | Object | Yes | {} | Information returned to the client, mainly including some strategy results |
The verification pass identifier is: the status field in the response is success, and the result field is also success
The parameters included in captcha_args are as follows:
| Parameter Name | Type | Required | Example | Description |
|---|---|---|---|---|
| model_cnn | int | Yes | 0 | CNN sliding track model judgment result, 0 indicates normal track, 1 indicates abnormal track |
| model_probability | int | Yes | 0 | Whether it is a captcha platform request, 0 for normal users, 1 for captcha requests, it is recommended to handle it in real-time |
| used_type | String | Yes | slide | The verification method used this time |
| web_simulator | int | Yes | 0 | Whether it is a simulator, 0 indicates a normal browser, 1 indicates a simulator |
| user_ip | String | Yes | "127.0.0.1" | User IP when verification passes |
| user_referer | String | Yes | "" | User request Referer when verification passes |
| cnn_records | int | Yes | 0 | Whether there was a single prediction of an abnormal track during the entire process |
| user_agent | String | Yes | "User-Agent" | User UA when verification passes |
| lot_number | String | Yes | "9b57c5289e" | User verification serial number |
Note: model_probability is the captcha identifier. When this identifier is 1, it is recognized as an abnormal captcha request. It is recommended to handle it later by the business side.
When the result field in data is success, it indicates that the verification result is passed
Response Example
{
"status": "success",
"data": {
"captcha_args": {
"cnn_records": 0,
"lot_number": "a989b864ad08cc08f270c22d9ab1fba0",
"model_cnn": 0,
"model_probability": 0,
"used_type": "slide",
"user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
"user_ip": "59.174.224.96",
"user_referer": "http://127.0.0.1:5000/",
"web_simulator": 0
},
"reason": "validate success",
"result": "success"
}
}
Java Code Integration Example
Taking the business side using Java language development as an example, the reference code is as follows:
package com.engagelab.demo.controller;
import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
import org.json.JSONObject;
import org.springframework.http.*;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.util.LinkedMultiValueMap;
import org.springframework.util.MultiValueMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;
import java.util.HashMap;
import java.util.Map;
@RestController
public class MainController {
@RequestMapping(value = "/login", method = {RequestMethod.GET})
public String userLogin(@RequestParam Map<String, String> getParams) {
// 1. Initialize parameter information, needs to be consistent with the captchaId used by the frontend, or can be placed in the configuration file
String captchaId = "37830cbb24f5a2134d39c7cf3093bc14";
String captchaKey = "ab8aeb88a3c30e170ab04af8ada6e6ec";
// domain is the domain name of EngageLab's verification code service
String domain = "https://captcha-api.engagelab.com";
// 2. Get the verification serial number and other parameters passed from the frontend after user verification
String lotNumber = getParams.get("lot_number");
String captchaOutput = getParams.get("captcha_output");
String passToken = getParams.get("pass_token");
String genTime = getParams.get("gen_time");
// 3. Generate signature
String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);
// 4. Upload verification parameters to the secondary verification interface to validate the user verification status
Map<String, String> queryParams = new HashMap<>();
queryParams.put("captcha_id", captchaId);
queryParams.put("lot_number", lotNumber);
queryParams.put("captcha_output", captchaOutput);
queryParams.put("pass_token", passToken);
queryParams.put("gen_time", genTime);
queryParams.put("sign_token", signToken);
String url = String.format(domain + "/validate");
SimpleClientHttpRequestFactory clientHttpRequestFactory = new SimpleClientHttpRequestFactory();
clientHttpRequestFactory.setConnectTimeout(3000); // Set connection timeout
clientHttpRequestFactory.setReadTimeout(1500); // Set Read timeout
RestTemplate client = new RestTemplate();
client.setRequestFactory(clientHttpRequestFactory);
JSONObject responseJsonObject = new JSONObject();
try {
RequestEntity<Map<String, String>> requestEntity = RequestEntity.post(url).accept(MediaType.APPLICATION_JSON).body(queryParams);
ResponseEntity<String> response = client.exchange(requestEntity, String.class);
String resBody = response.getBody();
responseJsonObject = new JSONObject(resBody);
}catch (Exception e){
responseJsonObject.put("status", "success");
responseJsonObject.put("data", new JSONObject("{\"result\": \"success\", \"reason\": \"request captcha api fail\"}"));
}
JSONObject res = new JSONObject();
String status = responseJsonObject.getString("status");
if (status.equals("success")) {
String data = responseJsonObject.getJSONObject("data").getString("result");
if (data.equals("success")) {
res.put("login", "success");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
} else {
res.put("login", "fail");
res.put("reason", responseJsonObject.getJSONObject("data").getString("reason"));
}
JSONObject captchaArgs = responseJsonObject.getJSONObject("data").getJSONObject("captcha_args");
Integer model_probability = captchaArgs.getInt("model_probability");
System.out.println("The captcha recognition result is: " + model_probability);
} else {
res.put("login", "fail");
res.put("reason", "captcha verify fail");
}
return res.toString();
}
}









