TrustCaptcha · Bot protection

Python CAPTCHA Integration

Add a Python CAPTCHA to your backend: TrustCaptcha verifies each result on your server and stops bot sign-ups, spam submissions and abuse. It works with any of our frontend widgets, and your users never see a puzzle. EU-hosted and GDPR-compliant.

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.

CAPTCHA security rules of a demo CAPTCHA.

2. Integrate the CAPTCHA widget into your frontend

Integrate the CAPTCHA widget into your website or app. The CAPTCHA widget guide in our documentation has step-by-step instructions.

Read the documentation

The CAPTCHA widget will then be displayed on your website or app:

Pre-built frontend integrations
Our pre-built frontend integrations add the CAPTCHA widget to your website or application. If there is none for your frontend technology yet, your developers can integrate the widget themselves using our documentation or ask our support team for a pre-built integration.

3. Validate the CAPTCHA result in your backend

The following steps show how a Python backend fetches the CAPTCHA verification result from our server and decides what to do with it. For the full instructions, read the CAPTCHA integration guide for Python in our documentation.

Read the documentation

First, install our TrustCaptcha Python dependency:

Install

bash

pip install trustcaptcha

Fetch the verification result from our server with the verification token and your API key:

Fetch Result

Python

# Retrieving the verification result
try:
  trust_captcha = TrustCaptcha("<your_api_key>")
  verification_result = trust_captcha.get_verification_result("<verification_token_from_your_client>")
except Exception as e:
  # Fetch verification result failed - handle error
  pass

Based on the verification result and your own requirements, decide how to proceed:

Handle Result

Python

# Act on the verification result
if not verification_result.verification_passed or verification_result.score > 0.5:
  # Verification failed or bot score > 0.5 - possible automated request
  pass

Need detailed information about the Python CAPTCHA integration?
Our Python CAPTCHA integration guide has the detailed instructions, and our CAPTCHA samples repository on GitHub has a complete integration example.

Other backend technology instead of Python?
If you run something other than Python on your server, or have several backends, pick a different integration here. If we have no pre-built integration for your backend technology yet, your developers can integrate the CAPTCHA verification themselves using our documentation or ask our support team for a pre-built integration.

4. Test your integration

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

FAQs

Do I still need a frontend (website or app) when I validate in Python?

Yes. The CAPTCHA always needs a frontend widget that the user can solve. After solving, the widget creates a verification token. Your Python backend must receive that verification token to validate the result.

How does a Python CAPTCHA check work, step by step?

1) Your frontend shows the CAPTCHA widget. 2) The user solves it and your frontend receives a verification token. 3) Your frontend sends that verification token to your Python backend. 4) Your Python backend calls the TrustComponent verification API to fetch the result. 5) Based on the result, you allow, block, or add an extra step.

Does it matter how I send the verification token to my Python backend?

No. You can send the verification token in a form submit, in a JSON body, as a header, or any other method that fits your system. The important part is that your Python backend receives the verification token and validates it on the server side.

What information do I get back from the validation result?

You always get two values: verification passed and a bot score. Verification passed is the hard yes/no decision (for example, it is false when your security rules block a request). The bot score is a risk rating from 0 (very likely human) to 1 (very likely bot), so you can fine-tune how strict you want to be.

What bot score threshold should I start with?

A practical starting point is 0.5: allow requests below 0.5 and block requests above 0.5 (only if verification passed is true). You can adjust the threshold to match your risk level, use different thresholds for different actions (login vs. contact form), or use a step-up flow (for example: allow, then email verification, then block).

How long is a verification token valid, and can I reuse it?

By default, the verification token is single-use and valid for 15 minutes. On the Enterprise plan you can extend the validity and allow a limited number of retrievals. We recommend keeping the default for security reasons.

Losing leads to CAPTCHAs?

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

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 Python application with TrustCaptcha in just a few steps!

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

Get started Contact sales