Technical CAPTCHA concept

To better understand the technical integration steps mentioned above, it helps to have a rough understanding of how TrustCaptcha works technically. It can be divided into three steps:

1. Solve CAPTCHA: A user solves the CAPTCHA on your website and receives a verification token
2. Retrieve the Result: You send the verification token to your backend and retrieve the verification result from our servers
3. Next Steps: Based on the verification result, you individually determine the next steps.

The following sequence diagram illustrates the entire TrustCaptcha process.

sequenceDiagram
    participant Client
    participant YourWebsite
    participant YourBackend
    participant TrustcaptchaBackend
    autonumber
    Client->>+YourWebsite: Triggers the CAPTCHA
    Note over YourWebsite: Solve CAPTCHA (frontend-widget)
    YourWebsite->>+TrustcaptchaBackend: Contact TrustCaptcha services
    TrustcaptchaBackend-->>-YourWebsite: Returns a proof-of-work challenge
    YourWebsite->>+TrustcaptchaBackend: Sends proof-of-work challenge results
    TrustcaptchaBackend-->>-YourWebsite: Returns further proof-of-work challenge or the verification token
    Note over YourWebsite: Fetch result (backend-integration/api-call)
    YourWebsite->>+YourBackend: Send the verification token
    YourBackend->>+TrustcaptchaBackend: Request the result with the verification token
    TrustcaptchaBackend-->>-YourBackend: Returns the verification result
    Note over YourBackend: Next steps (your choice)
    YourBackend-->>-YourWebsite: Set next steps based on the result
    YourWebsite-->>-Client: Next steps for the client

The TrustCaptcha CAPTCHA widget is a small web component that can be integrated into any front end. To do this, simply add the TrustCaptcha dependency to the respective page or project. A new HTML element called trustcaptcha-component will then be available, which can be integrated into any HTML.

<form>
  <!-- your input fields -->
  <trustcaptcha-component
    sitekey="<your_site_key>"
  ></trustcaptcha-component>
  <!-- further input fields / submit button -->
</form>

The TrustCaptcha component must be added to a form element. If you want to use the CAPTCHA on its own, simply create an empty form element and add the CAPTCHA there.

You can find more detailed instructions for the widget integration and all our prebuilt widget integration libraries in the CAPTCHA widget overview.

(Corresponds to steps 1 to 5 of the sequence diagram shown above.)

When a user starts the CAPTCHA, it resolves completely on its own. No further interaction from the user is required. A visual spinner and corresponding ARIA labels indicate that the verification is in progress.

During the review, two things normally happen simultaneously:

1. Risk analysis: When the CAPTCHA is launched and while it is running, the widget transmits a series of static data and behavioral information to our server. Based on this data, the server determines a risk assessment, known as the bot score.

2. Intelligent proof-of-work: Parallel to the risk analysis, the client usually receives at least one proof-of-work task, which is solved automatically by the widget. This is a cryptographic puzzle that becomes more difficult and takes longer to solve the greater the current risk of attack by the client. Regardless of the bot score, this is intended to make large-scale bot and spam attacks unprofitable for attackers.

There may be exceptions to this in exceptional cases. For example, the proof-of-work part can be skipped with the help of a bypass key or IP allow list.

Once the CAPTCHA has been completely solved and completed, a verification token is generated. With the help of this token, the CAPTCHA verification result can be retrieved and validated on the server side in the next step.

You can find more information in the CAPTCHA widget overview.

Send the verification token you receive after successfully solving the CAPTCHA to your backend. On the server side, you can now retrieve the CAPTCHA verification result from our servers using a simple REST API call. This can be done either with one of our ready-made integrations or by implementing the API call yourself.

The verification result now contains all the important information. Among other things, it provides information on whether the CAPTCHA has been completed and passed, what the bot risk is, and how we arrived at this assessment. Based on the verification result, you can now determine your individual next steps.

You can find more information about validating the result in the result validation overview.