CAPTCHA-Token in eigene Formulare einsetzen: Referenz für Standardintegration

Anwendungsbereich: Diese Referenz gilt ausschließlich für Ihre eigenen oder ausdrücklich autorisierten QA-, Staging- und Produktionsumgebungen. Sie beschreibt die Standardintegration eines CAPTCHA-Tokens in Ihre eigenen Formulare – nicht das Manipulieren fremder Seiten oder unautorisierte Workflows.

Ein von CaptchaAI gelöster CAPTCHA-Token gehört in genau ein Ziel: das versteckte Eingabefeld, das der jeweilige Anbieter in Ihrem Formular vorsieht – bei reCAPTCHA das Feld g-recaptcha-response, bei Cloudflare Turnstile cf-turnstile-response. Sie tragen den Wert dort ein, senden das Formular ab und prüfen den Token anschließend serverseitig. Mehr braucht die Standardintegration in aller Regel nicht.

Diese Referenz fasst die drei Muster zusammen, die dabei praktisch relevant sind: das versteckte Feld in einer klassischen HTML-Form, der Token im JSON-Body eines eigenen Frontends und die serverseitige Verifizierung. Alle Beispiele beziehen sich auf Formulare, die Sie selbst betreiben.

Welches Feld erwartet welcher Anbieter?

Jeder Anbieter legt einen festen Feldnamen fest. Halten Sie sich exakt daran – ein abweichender Name führt dazu, dass der Token stillschweigend ignoriert wird.

CaptchaAI liefert für reCAPTCHA v2/v3 und Turnstile jeweils den Token-String. Bei Cloudflare Challenge erhalten Sie stattdessen ein cf_clearance-Cookie, das in denselben Session-Kontext gehört wie der Solve – gleicher User-Agent, gleicher Proxy.

Muster 1: Verstecktes Feld in einer eigenen HTML-Form

In einer klassisch serverseitig verarbeiteten Form enthält Ihr Markup bereits ein verstecktes Feld mit dem vorgesehenen Namen. Vor dem Absenden schreiben Sie den gelösten Token hinein:

<form id="signup-form" method="post" action="/api/signup">
  <input name="email" type="email" required />
  <input name="g-recaptcha-response" type="hidden" />
  <button type="submit">Konto anlegen</button>
</form>

async function submitWithCaptcha(form, token) {
  form.querySelector('[name="g-recaptcha-response"]').value = token;
  form.submit();
}

Der Browser überträgt das Feld anschließend wie jedes andere Formularfeld an Ihren Endpunkt. Entscheidend ist nur, dass zwischen dem Eintragen und dem Absenden möglichst wenig Zeit vergeht – dazu gleich mehr.

Muster 2: Token im JSON-Body des eigenen Frontends

Sendet Ihr Frontend die Daten als JSON an eine eigene API, gehört der Token in den Request-Body als reguläres Feld – niemals in einen benutzerdefinierten Header:

await fetch('/api/contact', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, message, captcha: token }),
});

Der Schlüssel im JSON-Objekt ist frei wählbar (hier captcha), solange Ihr Backend genau diesen Schlüssel ausliest und den Wert danach gegen den offiziellen Endpunkt prüft.

Muster 3: Serverseitige Verifizierung

Unabhängig vom gewählten Muster gilt: Ihr eigener Server muss den Token gegen den offiziellen Verifizierungsendpunkt des Anbieters prüfen, bevor er die Anfrage verarbeitet. Die clientseitige Anzeige allein ist kein Nachweis.

import requests

def verify_recaptcha(token: str, secret: str) -> bool:
    resp = requests.post(
        'https://www.google.com/recaptcha/api/siteverify',
        data={'secret': secret, 'response': token},
        timeout=10,
    )
    resp.raise_for_status()
    payload = resp.json()
    return bool(payload.get('success')) and payload.get('score', 1.0) >= 0.5

Bei reCAPTCHA v3 werten Sie zusätzlich das score-Feld aus (0,0 bis 1,0) und legen einen Schwellenwert fest – 0,5 ist ein üblicher Startpunkt, den Sie an Ihr Risikoprofil anpassen. Für Turnstile entfällt der Score; hier genügt das success-Flag der Antwort.

Ablauf und Timing

Ein Token ist nur kurz gültig. Tragen Sie ihn deshalb erst unmittelbar vor dem Absenden ein und halten Sie ihn nicht auf Vorrat. Die üblichen Fristen:

Läuft die Frist ab, lehnt der Verifizierungsendpunkt den Token mit timeout-or-duplicate ab. Fordern Sie dann pro Aktion einen frischen Token an, statt einen alten erneut zu verwenden.

Beispiel: Registrierungsformular in einer Shopware-Staging-Umgebung

Ein typisches DACH-Szenario: Sie prüfen das Registrierungsformular eines Shopware- oder JTL-Shops in Ihrer eigenen Staging-Umgebung, etwa unter https://staging.shop.example.test. Das Formular schützt ein reCAPTCHA v2. Im QA-Lauf lösen Sie die Abfrage über CaptchaAI, tragen den Token in das Feld g-recaptcha-response ein und senden ab. Ihr Backend – ob auf Hetzner, IONOS oder netcup betrieben – ruft anschließend siteverify auf und legt das Konto erst nach success: true an. So testen Sie den vollständigen Pfad vom CAPTCHA bis zur Kontoerstellung, ohne die Abfrage manuell anklicken zu müssen.

Enthält eine Seite mehrere Widgets, besitzt jedes seine eigene g-recaptcha-response-Ablage. Wählen Sie das Feld dann gezielt über das umgebende Formular aus, statt pauschal das erste Element der Seite zu befüllen.

Häufige Fehler in eigenen Integrationen

FAQ

Wie lange ist ein gelöster Token gültig?

Bei reCAPTCHA v2 und v3 etwa 120 Sekunden, bei Turnstile bis zu 300 Sekunden. Setzen Sie den Token also erst kurz vor dem Absenden ein und fordern Sie bei Zeitüberschreitung einen neuen an.

Muss ich den Token zwingend serverseitig prüfen?

Ja. Erst der Abgleich mit dem offiziellen siteverify-Endpunkt bestätigt, dass der Token echt und gültig ist. Eine reine Anzeige im Browser lässt sich fälschen und ersetzt die Prüfung nicht.

Was bedeutet timeout-or-duplicate in der Antwort?

Dass der Token abgelaufen ist oder bereits verwendet wurde. Tokens sind Einmalwerte – fordern Sie pro Formularabsendung einen frischen an und senden Sie ihn zügig ab.

Kann ich denselben Token für mehrere Formulare wiederverwenden?

Nein. Jeder Token ist an eine einzelne Absendung gebunden; eine zweite Verwendung scheitert an der serverseitigen Prüfung. Für getrennte Aktionen lösen Sie jeweils neu.

Verwandte Leitfäden

• CaptchaAI Schnellstart
• reCAPTCHA v2 per API lösen
• Cloudflare Turnstile per API lösen
• Token in eigenen Backends wiederverwenden

Standardkonforme Token-Integration in eigenen Formularen – Starten Sie mit CaptchaAI.