Client-Token prüfen

Achtung

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

Senden Sie den Rumpf als JSON mit der Kopfzeile Content-Type: application/json. 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.

Hinweis

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.
`500`	Unerwarteter Fehler auf dem Server. Die Antwort enthält keinen JSON-Rumpf.

Fehlende oder fehlerhafte Felder führen nicht zu einem eigenen Statuscode. Der Endpunkt antwortet mit dem Statuscode 200, setzt success auf false und nennt den Grund im Feld error-codes.

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`	Nennt, ob eine echte Prüfung stattgefunden hat. Das Feld ist in jeder Antwort vorhanden. Der Wert `false` steht 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.

Achtung

Eine Antwort mit train: true bedeutet, dass die Anfrage nicht geprüft wurde und jede Übermittlung als erfolgreich gilt. Der Fall tritt ein, wenn der Schutz des Sitekeys in der Ansicht Configuration abgeschaltet ist. Ein unbekannter Sitekey und ein nicht passendes Secret führen dagegen zu success: false mit der Fehlerkennung invalid-input-sitekey beziehungsweise invalid-input-secret.

Achtung

Für einen Sitekey, dessen Testphase abgelaufen ist, antwortet der Endpunkt mit success: true, ohne dass eine Prüfung stattgefunden hat. Das Feld train bleibt dabei false. Siehe Testphase abgelaufen.

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, ist leer oder länger als 255 Zeichen.
`invalid-input-sitekey`	Der Sitekey ist unbekannt, leer oder länger als 255 Zeichen.
`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.
`bad-request`	Der Rumpf der Anfrage ließ sich nicht als JSON lesen. Die Kopfzeile `Content-Type` fehlte oder war nicht `application/json`, oder der Rumpf war leer oder kein gültiges JSON.

Beispiele der Antwort

Token gültig:

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

Token ungültig:

{
  "success": false,
  "train": false,
  "error-codes": ["invalid-input-response"]
}

Prüfung übersprungen, Schutz des Sitekeys abgeschaltet:

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

Sitekey unbekannt:

{
  "success": false,
  "train": false,
  "error-codes": ["invalid-input-sitekey"]
}

Zugangsdaten prüfen

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