Glossary

This document explains frequent used terms for GeeTest captcha.

id

The id, namely captcha ID, is the public key for the captcha verification. It consists of a 32-bit string and is visible to the public. Besides, it’s a unique identifier for the captcha, which could help to distinguish between different web pages or different modules. You can create it in the GeeTest dashboard. Please use different captcha ID for each verification context.

key

The private key for the captcha verification. It consists of a 32-bit string. The private key corresponds with only one public key and vice versa. The GeeTest cloud server uses the private key to perform the data encryption and ensure security. After created a captcha ID (public key) in the dashboard, the system will automatically generate a private key for it. Please keep your private key a secret.

challenge

The challenge is the unique ID for a verification event. It can be used only once. It is generated when the integrated server SDK registers in GeeTest cloud server. The challenge is valid for only 10 minutes.

Note: The challenge of Slide captcha has two extra random numbers at the end string, which is different from other captcha types.

validate

The validate is a string returned by ajax and can mark whether the current captcha has been passed. If the visitor failed to pass the captcha or is blocked, the ajax will not return the validate.

seccode

The seccode is the certification for the secondary verification.

forbidden

The forbidden is one of the returned verification results. It indicates that the visitor failed to pass the captcha, which is evaluated with the submitted verification data.

user_id

The user_id is used to provide advanced data analysis service. As a unique identifier of the end user, user_id can associate user with verification events and mark the risky account for customers. This parameter is passed to the GeeTest server through the server SDK. If you have any concerns for the leakage of user information, you can preprocess (e.g. hash) the user_id before uploading it.

Failback mode

Failback mode is an emergency solution for downtime. GeeTest’s captcha is designed to provide a stable and secure service. In some unavoidable case or force majeure, Failback mode could be used to ensure normal operation in downtime. Please CHCEK whether the failback mode has been integrated successfully after you have finished the integration.

The customer’s server can check the availability of GeeTest server with heartbeat detection. Entering the failback mode means that the service is temporarily unavailable. In this mode, the captcha only uses your client and server to process the verification. See the failback mode flowchart

If the server and the client of the GeeTest captcha are correctly integrated, the failback mode is the default mode when the Geetest server is down.

API1

API1 is used to get challenge at the beginning of the verification, and encrypts the challenge with the key in customer’s server, in order to prevent anyone from bypassing the customer’s server and obtain the challenge. At the same time, the API1 can checks if the GeeTest cloud server can be connected successfully, return the available status to the client and cache in the session.

API2

API2 is used to perform the secondary verification after the core verification is completed. It can help to check the authenticity of the result and ensure that the challenge could be only used once.

If the GeeTest Cloud server status stored in API1 shows it’s unavailable, the secondary verification in API2 will also be processed locally on customer’s servers. Please do check if API2 works properly after the integration.

fullpage

The fullpage is collected in the pre-verification stage. When the end user clicks at the captcha button, the collected data including mouse track, environment attributes, and so on, will be uploaded to GeeTest cloud server. Then, GeeTest cloud server will analysis the risk level and decide whether to provide an extra captcha challenge or allow users to pass the test.

Secondary verification

After the user finishes interacting with captcha challenge or captcha button and GeeTest cloud server completes the analysis, the client will send an API2 request to server. The API2 will check with GeeTest cloud server for the verification result. Besides, it will set the current challenge to be invalid, in order to prevent this challenge from being used twice. These processes are called secondary verification. It can ensure the reliability of the verification result.