TrustComponent
Spring Boot
TrustCaptcha · Bot protection

Spring Boot CAPTCHA Integration

Add a Spring Boot CAPTCHA to a controller in a few lines of Java. It stops bot spam on logins, sign-ups and contact forms and leaves Thymeleaf templates, Bean Validation and Spring Security as they are. EU-hosted, GDPR-compliant, no image puzzles.

Quickstart

How the integration works

1. Create a CAPTCHA

Create a user account or log in with an existing one. Then create a new CAPTCHA or pick an existing one. If you want to try TrustCaptcha first, every plan comes with a 14-day free trial.

The CAPTCHA overview page shows your site key and license key, and you create your API key there. Add your website’s domains to the authorized domains in the CAPTCHA security rules so they can use your CAPTCHA.

Start of the CAPTCHA creation form.
CAPTCHA security rules of a demo CAPTCHA.

2. Add the CAPTCHA widget to your Thymeleaf template

Drop the TrustCaptcha widget into the Thymeleaf form you want to protect. As soon as a visitor interacts with the form, the CAPTCHA runs in the background and adds a hidden tc-verification-token field on submit. Spring Boot will hand it to your controller like any other form parameter.

contact.html
HTML
<script type="module" src="https://cdn.trustcomponent.com/trustcaptcha/3.0.x/trustcaptcha.esm.min.js"></script>

<form th:action="@{/contact}" method="post">
    <input type="email" name="email" required>
    <trustcaptcha-component sitekey="<your_site_key>"></trustcaptcha-component>
    <button type="submit">Send</button>
</form>

The CAPTCHA widget will then be displayed inside your form:

CAPTCHA start

Need detailed information about the CAPTCHA widget integration?
Our documentation has the full widget reference, including themes, languages and custom design.

Read the documentation

3. Validate the token in your Spring Boot controller

In your Spring Boot controller, take the verification token from the form, look up the result via our Java library, and decide whether to accept the request.

First, install our TrustCaptcha Java library:

pom.xml
XML
<dependency>
  <groupId>com.trustcomponent</groupId>
  <artifactId>trustcaptcha</artifactId>
  <version>3.0.0</version>
</dependency>

Then validate the token inside your controller and act on the result:

ContactController.java
Java
@PostMapping("/contact")
public String submit(@RequestParam("tc-verification-token") String token, Model model) {

  VerificationResult result;
  try {
    result = TrustCaptcha.getVerificationResult("<your_api_key>", token);
  } catch (CaptchaFailureException e) {
    return "contact"; // verification failed — show the form again
  }

  if (!result.isVerificationPassed() || result.getScore() > 0.5) {
    return "contact"; // looks like a bot — block it
  }

  // CAPTCHA passed — process the request
  return "contact-success";
}

Need detailed information about the Spring Boot CAPTCHA integration?
For full step-by-step instructions, including a Bean Validation refactor for projects with several protected endpoints, please read our documentation.

Read the documentation

Other backend framework instead of Spring Boot?
If you use a different framework, pick the matching recipe here. If your framework isn’t listed, your software developers can integrate the verification themselves using our documentation or ask our support team for a pre-built integration.

Actix Web
ASP.NET Core
Axum
Django
Echo
Express
FastAPI
Fastify
Fiber
Flask
Gin
Hapi
Laravel
Micronaut
NestJS
Next.js
Quarkus
Ruby on Rails
Sinatra
Spring Boot
Symfony

4. Test your integration

TrustCaptcha is now active. Send a test request and check that it goes through.

CAPTCHA done

FAQs

Which Spring Boot versions are supported?
TrustCaptcha runs on every modern Spring Boot version (2.x and 3.x). The verification itself is just a regular Java call inside your controller, so you don't need a Spring Boot starter from us.
Where should the Spring Boot CAPTCHA verification happen?
Inside the controller method that receives the form submission, before you persist data or send any email. The CAPTCHA token arrives as a regular form parameter (default name: "tc-verification-token"), so you can read it with @RequestParam like any other field.
Can I use TrustCaptcha together with Spring Security?
Yes. TrustCaptcha sits at the application layer (your controller), independent of Spring Security. It does not replace authentication, authorization or CSRF protection. Leave those enabled as they are. The CAPTCHA simply confirms that the request was made by a human.
Can I trigger CAPTCHA validation through Bean Validation (@Valid)?
Yes. For projects with several protected endpoints, the cleanest pattern is a custom Bean Validation annotation (e.g. @TrustCaptchaToken) on a DTO field. Adding @Valid to the controller parameter then runs the verification as part of the normal validation pipeline.
Does TrustCaptcha work with WebFlux / reactive controllers?
Yes. The Java SDK is blocking, so in a reactive endpoint you wrap the verification call in Mono.fromCallable(...).subscribeOn(Schedulers.boundedElastic()) to keep the event loop free. From the SDK's point of view nothing changes.
Where should I store the CAPTCHA API key in a Spring Boot project?
Treat it like any other secret: put it in application.yml or application.properties under a key like trustcaptcha.api-key, and inject it with @Value("${trustcaptcha.api-key}"). In production, fill it from an environment variable or a secret manager, and never commit it to your repo.
Losing leads to CAPTCHAs?

TrustCaptcha blocks spam and bots, not customers. No puzzles, GDPR-compliant, EU-hosted.

CAPTCHA start
CAPTCHA done
No puzzles for visitors
The check runs in the background while visitors type, so more people finish your forms instead of giving up.
GDPR-compliant
Hosted in the EU, no cookies, encrypted transmission and automatic data deletion. Every customer gets a Data Processing Agreement.
Multi-layer security
Adaptive proof-of-work and risk scoring stop abuse early, even when attack traffic spikes.
Full control
Set the sensitivity, keep allow and block lists and use geoblocking. You decide how strict the check is.

Protect your Spring Boot application with TrustCaptcha in just a few steps!

  • EU-hosted & GDPR-compliant
  • No puzzles
  • Try free for 14 days