TrustComponent
Axum
TrustCaptcha · Bot protection

Axum CAPTCHA Integration

Set up an Axum CAPTCHA with a few lines of Rust. TrustCaptcha stops bot spam on logins, signups and contact forms, and a shared instance in Axum's typed state plus a small async helper keep your handlers tidy. 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 Axum handler serves. The widget runs the CAPTCHA in the background and adds a hidden tc-verification-token field on submit, which axum::extract::Form deserializes into your struct.

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 Axum handler

In your Axum handler, take the verification token from the form, look up the result via our Rust crate, and decide whether to accept the request.

First, install our TrustCaptcha Rust crate:

Install
bash
cargo add trustcaptcha@^3.0

Then validate the token inside your Axum handler and act on the result:

src/main.rs
Rust
use axum::{extract::Form, http::StatusCode, response::IntoResponse};
use serde::Deserialize;
use trustcaptcha::trust_captcha::TrustCaptcha;

#[derive(Deserialize)]
struct ContactForm {
    email: String,
    #[serde(rename = "tc-verification-token")]
    tc_verification_token: String,
}

async fn submit(Form(form): Form<ContactForm>) -> impl IntoResponse {
    let trust_captcha = match TrustCaptcha::builder("<your_api_key>").build() {
        Ok(tc) => tc,
        Err(_) => return (StatusCode::INTERNAL_SERVER_ERROR, "CAPTCHA setup failed.").into_response(),
    };

    let result = match trust_captcha.get_verification_result(&form.tc_verification_token).await {
        Ok(r) => r,
        Err(_) => return (StatusCode::BAD_REQUEST, "CAPTCHA verification failed.").into_response(),
    };

    if !result.verification_passed || result.score > 0.5 {
        return (StatusCode::BAD_REQUEST, "CAPTCHA verification failed.").into_response();
    }

    // CAPTCHA passed — process the request
    (StatusCode::OK, "Thanks!").into_response()
}

Need detailed information about the Axum CAPTCHA integration?
For full step-by-step instructions, including a shared TrustCaptcha via typed state and a reusable verify_token helper, please read our documentation.

Read the documentation

Other backend framework instead of Axum?
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

Where does the Axum CAPTCHA check go?
Inside the async handler that receives the form submission. Bind the body with axum::extract::Form<MyForm>, where MyForm carries the CAPTCHA token via #[serde(rename = "tc-verification-token")], then call our Rust crate to fetch the verification result.
How do I share a single TrustCaptcha across handlers?
Build it once at startup, wrap it in Arc, put it in an AppState struct and attach it to the router with .with_state(state). Each handler then receives State<AppState> and reads the SDK from there. The Arc keeps cloning cheap.
Should I extract the CAPTCHA check into a custom Axum extractor?
It's tempting, but FromRequestParts only sees request parts (headers, URI), not the form body, and Form<...> consumes the body. The cleanest pattern is a small async verify_token(...) helper called from inside each protected handler with the ? operator.
Does the Rust SDK fit Axum's Tokio runtime?
Yes. The crate is async/reqwest-based, so you await the verification call directly inside your async fn handler. You need no blocking workarounds or thread-pool tricks.
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 Axum application with TrustCaptcha in just a few steps!

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