TrustComponent
Django
TrustCaptcha · Bot protection

Django CAPTCHA Integration

Set up a Django CAPTCHA in your view with a few lines of Python. TrustCaptcha stops bot spam on logins, signups and contact forms, and CSRF protection and your existing forms.Form classes keep working. 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 Django template

Drop the TrustCaptcha widget into the Django template that renders your form. The widget runs the CAPTCHA in the background and adds a hidden tc-verification-token field on submit, which arrives on request.POST like any other input.

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

<form method="post" action="{% url 'contact_submit' %}">
    {% csrf_token %}
    <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 Django view

In your Django view, take the verification token from request.POST, look up the result via our Python library, and decide whether to accept the request.

First, install our TrustCaptcha Python library:

Install
bash
pip install "trustcaptcha>=3.0.0,<4.0.0"

Then validate the token inside your Django view and act on the result:

contact/views.py
Python
from django.shortcuts import redirect, render
from django.views.decorators.http import require_POST
from trustcaptcha.trust_captcha import TrustCaptcha

@require_POST
def submit(request):
    token = request.POST.get("tc-verification-token", "")

    try:
        trust_captcha = TrustCaptcha("<your_api_key>")
        result = trust_captcha.get_verification_result(token)
    except Exception:
        return render(request, "contact.html", {"error": "CAPTCHA verification failed."})

    if not result.verification_passed or result.score > 0.5:
        return render(request, "contact.html", {"error": "CAPTCHA verification failed."})

    # CAPTCHA passed — process the request
    return redirect("contact_success")

Need detailed information about the Django CAPTCHA integration?
For full step-by-step instructions, including a Django Form integration that runs verification inside clean_*(), please read our documentation.

Read the documentation

Other backend framework instead of Django?
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 Django CAPTCHA check go?
Inside the view that handles the form submission, before saving the model or sending the email. The CAPTCHA token comes in as a regular form field on request.POST (default name: "tc-verification-token").
Does TrustCaptcha replace Django's CSRF protection?
No. CSRF and TrustCaptcha are independent layers, and both should stay enabled. Keep {% csrf_token %} in your template and the CSRF middleware in settings; TrustCaptcha only confirms that a human filled the form.
Can I integrate the CAPTCHA into a Django Form (forms.Form / ModelForm)?
Yes. Add a hidden CharField for the token (e.g. tc_verification_token) and put the verification call inside a clean_tc_verification_token method. Validation errors then surface on the bound form like any other field error.
Why is the form field named with an underscore (tc_verification_token), but the widget posts a dash (tc-verification-token)?
Python identifiers can't contain dashes, so the Form field uses tc_verification_token. The simplest fix is to set token-field-name="tc_verification_token" on the widget so the wire format matches the Form field.
Does TrustCaptcha work in async Django views?
Yes. The Python SDK is blocking, so wrap the call in sync_to_async inside an async view: result = await sync_to_async(trust_captcha.get_verification_result)(token). The event loop stays responsive while the verification runs.
Where should I keep the CAPTCHA API key in a Django project?
In an environment variable (e.g. TRUSTCAPTCHA_API_KEY) and expose it through settings.py as settings.TRUSTCAPTCHA_API_KEY. Read it from settings inside your view or form, never hard-code it.
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 Django application with TrustCaptcha in just a few steps!

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