TrustComponent
FastAPI
TrustCaptcha · Bot-Schutz

FastAPI CAPTCHA-Integration

Mit wenigen Zeilen Python richtest du ein FastAPI-CAPTCHA in einer Path-Operation ein. TrustCaptcha stoppt Bot-Spam in Logins, Registrierungen und Kontaktformularen über eine Depends()-Dependency, die zum asynchronen, typisierten Stil von FastAPI passt. EU-gehostet, DSGVO-konform und ohne Bilderrätsel.

Schnellstart

So funktioniert die Integration

1. CAPTCHA erstellen

Erstelle ein Benutzerkonto oder melde dich mit einem bestehenden Konto an. Dann erstellst du ein neues CAPTCHA oder wählst ein vorhandenes aus. Wenn du TrustCaptcha erst ausprobieren willst: Jeder Tarif startet mit einer 14-tägigen kostenlosen Testphase.

Auf der Übersichtsseite des CAPTCHAs findest du den Site Key und den License Key, und dort erstellst du auch deinen API-Key. Trage die Domains deiner Website in den Sicherheitsregeln des CAPTCHAs als autorisierte Domains ein, damit sie dein CAPTCHA nutzen dürfen.

Start des Formulars zur Erstellung eines CAPTCHA.
CAPTCHA-Sicherheitsregeln eines Demo-CAPTCHAs.

2. CAPTCHA-Widget in dein Formular einbauen

Binde das TrustCaptcha-Widget in das HTML-Formular ein, das dein FastAPI-Endpoint ausliefert. Das Widget läuft im Hintergrund und fügt beim Absenden ein verstecktes Feld tc-verification-token hinzu, das FastAPI über Form(..., alias="tc-verification-token") zur Verfügung stellt.

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>

Das CAPTCHA-Widget wird anschließend in deinem Formular angezeigt:

CAPTCHA-Widget vor dem Start

Detaillierte Informationen zur CAPTCHA-Widget-Integration?
Die vollständige Widget-Referenz mit Themes, Sprachen, eigenem Design und mehr findest du in unserer Dokumentation.

Dokumentation lesen

3. Token in deinem FastAPI-Endpoint validieren

Hole in deiner FastAPI-Path-Operation den Verifikationstoken aus dem Formular, rufe das Ergebnis über unsere Python-Library ab und entscheide, ob die Anfrage akzeptiert werden soll.

Installiere zunächst unsere TrustCaptcha-Python-Library:

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

Validiere dann den Token in deinem FastAPI-Endpoint und reagiere auf das Ergebnis:

main.py
Python
from fastapi import FastAPI, Form, HTTPException
from fastapi.concurrency import run_in_threadpool
from trustcaptcha.trust_captcha import TrustCaptcha

app = FastAPI()

@app.post("/contact")
async def submit(
    email: str = Form(...),
    tc_verification_token: str = Form(..., alias="tc-verification-token"),
):
    trust_captcha = TrustCaptcha("<your_api_key>")
    try:
        result = await run_in_threadpool(trust_captcha.get_verification_result, tc_verification_token)
    except Exception:
        raise HTTPException(status_code=400, detail="CAPTCHA verification failed.")

    if not result.verification_passed or result.score > 0.5:
        raise HTTPException(status_code=400, detail="CAPTCHA verification failed.")

    # CAPTCHA bestanden — Anfrage verarbeiten
    return {"status": "ok"}

Detaillierte Informationen zur FastAPI-CAPTCHA-Integration?
Die vollständige Schritt-für-Schritt-Anleitung, inklusive einer wiederverwendbaren Depends()-Dependency für Projekte mit mehreren geschützten Endpunkten, findest du in unserer Dokumentation.

Dokumentation lesen

Anderes Backend-Framework statt FastAPI?
Wenn du ein anderes Framework nutzt, wähle hier das passende Rezept aus. Ist dein Framework nicht aufgeführt, können deine Softwareentwickler die Verifizierung mithilfe unserer Dokumentation selbst integrieren oder unser Support-Team nach einer vorgefertigten Integration fragen.

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. Integration testen

TrustCaptcha ist jetzt aktiv. Schick eine Testanfrage ab und prüfe, ob sie durchgeht.

CAPTCHA abgeschlossen

Häufige Fragen

Wo gehört die Prüfung des FastAPI-CAPTCHAs hin?
In der Path-Operation, die das Formular-Submit verarbeitet, oder bei mehreren geschützten Endpunkten in einer eigenen Depends()-Dependency. Beides funktioniert gleich: Du holst den Token aus einem Form(...)-Parameter, rufst die Verifizierung auf und wirfst bei einem Fehler eine HTTPException.
Wie lese ich den CAPTCHA-Token aus einem Form-Post?
Deklariere ihn als Form-Parameter mit Form(...) und einem Alias für den Namen mit Bindestrich: tc_verification_token: str = Form(..., alias="tc-verification-token"). FastAPI mappt das versteckte tc-verification-token-Feld des Widgets dann auf deinen Python-Parameter.
Kann ich eine einzige TrustCaptcha-Instanz über mehrere Endpunkte teilen?
Ja. Nutze FastAPIs Dependency Injection: Deklariere eine get_trust_captcha()-Funktion mit @lru_cache, die eine einzige TrustCaptcha-Instanz zurückgibt. Injiziere sie über Depends(get_trust_captcha) in deine Endpoints oder in eine verify_trust_captcha-Dependency.
Warum den Verifizierungs-Aufruf in run_in_threadpool kapseln?
Weil das Python-SDK synchron ist (blockierende I/O). In einem async-def-Endpoint würde ein direkter Aufruf den Event-Loop blockieren. run_in_threadpool(...) (oder asyncio.to_thread) übergibt den Aufruf an einen Worker-Thread, sodass andere Requests weiterlaufen können. In einem sync-def-Endpoint übernimmt FastAPI das automatisch.
Wie nutze ich TrustCaptcha mit einem JSON-Body statt eines Form-Posts?
Deklariere den Token in deinem Pydantic-Request-Modell und lies ihn aus dem Modell innerhalb des Endpoints oder der Dependency. Der Verifizierungs-Aufruf selbst bleibt gleich, egal wie der Token in dein Backend gekommen ist.
Leads verlieren wegen CAPTCHAs?

TrustCaptcha blockiert Spam und Bots, nicht deine Kunden. Keine Rätsel, DSGVO-konform, in der EU gehostet.

CAPTCHA-Start
CAPTCHA abgeschlossen
Keine Rätsel für Besucher
Die Prüfung läuft im Hintergrund, während Besucher tippen. So schicken mehr Menschen deine Formulare ab, statt vorher aufzugeben.
DSGVO-konform
In der EU gehostet, ohne Cookies, mit verschlüsselter Übertragung und automatischer Löschung. Jeder Kunde bekommt einen Auftragsverarbeitungsvertrag (AVV).
Mehrstufige Sicherheit
Adaptiver Proof-of-Work und Risiko-Scoring stoppen Missbrauch früh, auch wenn der Angriffs-Traffic plötzlich steigt.
Volle Kontrolle
Stell die Empfindlichkeit ein, pflege Allow- und Blocklisten und nutze Geoblocking. Du entscheidest, wie streng die Prüfung ist.

Schütze deine FastAPI-Anwendung in wenigen Schritten mit TrustCaptcha!

  • EU-hosted & DSGVO-konform
  • Keine Rätsel
  • 14 Tage kostenlos testen