Client-Token prüfen¶

Warning

Rufen Sie den Endpunkt ausschließlich von Ihrem Server auf. Das Secret bleibt auf dem Server und gehört nicht in den Quelltext der Seite.

Senden Sie eine POST-Anfrage an den Endpunkt /verify unter https://api.eu-captcha.eu/v1.

Beschreibung¶

Der Endpunkt prüft das Proof-of-Work-Token, das verify.js im Browser des Besuchers erzeugt hat. Die Prüfung stellt fest, ob die Berechnungen richtig ausgeführt wurden, ob das Token noch nicht verwendet wurde und ob Sitekey und Secret gültig sind.

Das Feld success der Antwort nennt das Ergebnis der Prüfung. Werten Sie zusätzlich immer das Feld train aus. Siehe die Beschreibung des Felds unter Antwortfelder.

Der Endpunkt verlangt keine Autorisierung über eine Kopfzeile. Die Anmeldung erfolgt über das Feld secret im Rumpf der Anfrage.

Anfrage¶

Der Rumpf der Anfrage enthält die folgenden Felder:

Feld	Typ	Erforderlich	Beschreibung
`sitekey`	`string`	ja	Öffentlicher Sitekey der Domain, in der das Widget eingebunden ist. Der Wert steht in der Ansicht Details des Sitekeys.
`secret`	`string`	ja	Zum Sitekey gehörendes Secret. Der Wert steht in der Ansicht Details des Sitekeys und bleibt auf dem Server.
`client_ip`	`string`	ja	IPv4- oder IPv6-Adresse des Besuchers. Übergeben Sie die Adresse des Besuchers, nicht die eines vorgeschalteten Proxys oder CDN. Werten Sie dazu die Kopfzeilen `X-Forwarded-For` oder `X-Client-IP` aus.
`client_token`	`string`	ja	Token aus `verify.js`. Der Wert erreicht Ihren Server im Formularfeld `eu-captcha-response`. Der Wert ist leer, falls das Widget nicht abgeschlossen hat, etwa bei abgeschaltetem JavaScript.
`client_user_agent`	`string`	ja	Kopfzeile `User-Agent` der Anfrage des Besuchers. Der Wert kennzeichnet die Art des Clients, falls kein Token berechnet wurde.

Note

Senden Sie das Feld client_token immer mit, auch mit leerem Wert. Aus unvollständigen und leeren Token lernt der Dienst über alle Prüfungen einschließlich der gescheiterten und erkennt Angriffe dadurch genauer.

Siehe Ansicht Details.

Beispiel¶

Rumpf der Anfrage:

{
  "sitekey": "1c87e240-0000-0000-0000-23ac9f99da68",
  "secret": "LqFgQA••••",
  "client_ip": "XXX.XXX.XXX.XXX",
  "client_token": "XVtHUQEx••••",
  "client_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36"
}

Antworten¶

Der Endpunkt liefert die folgenden Statuscodes:

Statuscode	Beschreibung
`200`	Ergebnis der Prüfung. Werten Sie `success` und `train` aus.
`400`	Im Rumpf der Anfrage fehlen erforderliche Felder, oder der Rumpf ist fehlerhaft.
`429`	Die Anzahl der Anfragen ist überschritten. Warten Sie die in der Kopfzeile `Retry-After` genannte Anzahl Sekunden ab und wiederholen Sie die Anfrage.
`500`	Unerwarteter Fehler auf dem Server.

Antwortfelder¶

Die Antwort mit dem Statuscode 200 enthält die folgenden Felder:

Feld	Typ	Beschreibung
`success`	`boolean`	`true`, falls das Token die Prüfung bestanden hat, sonst `false`. Werten Sie immer zusätzlich das Feld `train` aus, da `success` bei `train: true` den Wert `true` erhält.
`train`	`boolean` oder `null`	Nennt, ob eine echte Prüfung stattgefunden hat. Die Werte `false` und `null` stehen für den Regelbetrieb. Der Wert `true` steht für eine übersprungene Prüfung.
`error-codes`	`array`	Nur bei `success: false` vorhanden. Nennt die Gründe des Fehlschlags.

Warning

Eine Antwort mit train: true bedeutet, dass die Anfrage nicht geprüft wurde und jede Übermittlung als erfolgreich gilt. Der Fall tritt bei einem unbekannten Sitekey, bei einem nicht passenden Secret, bei abgeschaltetem Schutz des Sitekeys und bei jeder weiteren Störung der Prüfung ein. Prüfen Sie im Wirkbetrieb sofort die Werte von sitekey und secret.

Fehlerkennungen¶

Das Feld error-codes enthält die folgenden Werte. Das Format entspricht reCAPTCHA, hCaptcha und Turnstile.

Wert	Bedeutung
`invalid-input-secret`	Das Secret passt nicht zum Sitekey.
`invalid-input-sitekey`	Der Sitekey ist unbekannt.
`invalid-input-response`	Das Feld `client_token` war vorhanden, enthielt aber keinen gültigen Nachweis. Der Wert war fehlerhaft, nicht dekodierbar, ungelöst oder leer.
`timeout-or-duplicate`	Das Token wurde bereits verwendet, oder die Challenge ist abgelaufen. Jedes Token gilt einmal.
`missing-input-secret`	Das Feld `secret` fehlt oder ist keine Zeichenkette.
`missing-input-sitekey`	Das Feld `sitekey` fehlt oder ist keine Zeichenkette.
`missing-input-response`	Das Feld `client_token` fehlt oder ist keine Zeichenkette. Eine leere Zeichenkette gilt als vorhanden und führt zu `invalid-input-response`.
`missing-input-remoteip`	Das Feld `client_ip` fehlt oder ist keine Zeichenkette.

Beispiele der Antwort¶

Token gültig:

{
  "success": true,
  "train": false
}

Token ungültig oder bereits verwendet:

{
  "success": false,
  "train": false
}

Prüfung übersprungen, Zugangsdaten fehlerhaft:

{
  "success": true,
  "train": true
}

Fehlerantwort mit den Statuscodes 400, 429 und 500:

{
  "error": "missing_field",
  "message": "Required field 'sitekey' is missing."
}

Zugangsdaten prüfen¶

Zum Prüfen von Sitekey und Secret ohne ein Token siehe Sitekey und Secret prüfen.