TrustComponent
Quarkus
TrustCaptcha · Bot protection

Quarkus CAPTCHA Integration

Add a Quarkus CAPTCHA to a JAX-RS resource in a few lines of Java. It stops bot spam on logins, sign-ups and contact forms, runs in native images and works with MicroProfile Config and Hibernate Validator. 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 form

Drop the TrustCaptcha widget into the HTML form your Quarkus resource serves. The widget runs the CAPTCHA in the background and adds a hidden tc-verification-token field on submit, which Quarkus then exposes to your @POST method via @FormParam.

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

<form method="post" action="/contact">
    <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 Quarkus resource

In your Quarkus resource, 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 JAX-RS resource and act on the result:

ContactResource.java
Java
@Path("/contact")
public class ContactResource {

  @POST
  public Response submit(@FormParam("tc-verification-token") String token) {

    VerificationResult result;
    try {
      result = TrustCaptcha.getVerificationResult("<your_api_key>", token);
    } catch (CaptchaFailureException e) {
      return Response.status(400).entity("CAPTCHA verification failed.").build();
    }

    if (!result.isVerificationPassed() || result.getScore() > 0.5) {
      return Response.status(400).entity("CAPTCHA verification failed.").build();
    }

    // CAPTCHA passed — process the request
    return Response.ok("Thanks!").build();
  }
}

Need detailed information about the Quarkus 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 Quarkus?
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

Does the Quarkus CAPTCHA work with quarkus-rest and the older RESTEasy Classic?
Yes, both work the same way. The verification call is a regular Java method call inside your @POST resource method. Whether you use quarkus-rest (RESTEasy Reactive) or quarkus-resteasy-classic only changes the dependency name, not the integration code.
How do I read the CAPTCHA token in a JAX-RS resource?
It arrives as a regular form parameter named "tc-verification-token". Annotate the method parameter with @FormParam("tc-verification-token") and Quarkus hands you the value as a String.
Can I plug the CAPTCHA check into Hibernate Validator (@Valid)?
Yes. For projects with several protected endpoints, build a custom Bean Validation constraint (e.g. @TrustCaptchaToken) backed by a CDI-managed @ApplicationScoped validator that injects the API key via @ConfigProperty. The check then runs automatically whenever you mark a parameter with @Valid.
Where should I put the CAPTCHA API key in a Quarkus app?
In application.properties under a key like trustcaptcha.api-key, and read it with @ConfigProperty(name = "trustcaptcha.api-key"). For production, fill the value from an environment variable or your secret manager so the key never lands in your repo.
Does TrustCaptcha work in a Quarkus native image (GraalVM)?
Yes. The Java SDK works in JVM mode and in native builds. With quarkus-jackson on the classpath, the result type's reflection metadata is registered automatically, so no extra configuration is required for typical setups.
What about reactive endpoints that return Uni or Multi?
The Java SDK call is blocking, so wrap it in Uni.createFrom().item(...).runSubscriptionOn(Infrastructure.getDefaultWorkerPool()) inside a reactive resource. This keeps the I/O thread free while the verification call runs.
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 Quarkus application with TrustCaptcha in just a few steps!

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