logoDocument
Search
Login

Server Access

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.

image-20250427154654130

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.

image-20250427154749118

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. image-20250427154654130 image-20250427154749118 image-20250427154933547

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:

  1. 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.
  2. 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);
              
              String signToken = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, captchaKey).hmacHex(lotNumber);

            
This code block in the floating window
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" }
              
              {
    "lot_number": "f26d13345c9980c7705b9111b9398a0f",
    "captcha_id": "59bbe0f128f0624fdd185a6a2207aa54",
    "sign_token": "2e61e2f6d40e2896b18978fe6ae1416347fc43027ab7c875460d17ffa149dd7a",
    "pass_token": "79a4b7fc89d917b346d35286991bc9bca388a78bd31c20fa00907dcb8632611c",
    "gen_time": "1684826917",
    "captcha_output": "X4oDQ5p61MhE0Zpy5wQcl98WjrDdlDyL5B_VO0zPYnS9ITuz1ZZ6o0iw4Odk9f0AbAlzraqmeLGSmQWHPwJr2Vvf_Nm2Z0SMCn2ATME67e5UhMdopMgc8_zZi-SFRyH1"
}

            
This code block in the floating window
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" } }
              
              {
    "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"
    }
}

            
This code block in the floating window

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(); } }
              
              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();

    }
}

            
This code block in the floating window
icon
Contact Sales