Verifizierung des Tokens über Verifikations-API

Unser Widget fügt deinem Formular automatisch ein unsichtbares Input-Feld pc-token hinzu. Dieses Feld enthält ein Token, das du in deinem Backend verifizieren kannst.

Darüber kannst du sicherstellen, dass der Zugriff überprüft wurde und berechtigt ist (z.B. ob das Captcha ordnungsgemäß gelöst wurde).

Anfrage an die Verifikations-API

Die Verifikation erfolgt über unsere API (https://api.power-captcha.com/pcu/v1/verify). An diese Schnittstelle müssen folgende Parameter als JSON-Body per POST gesendet werden:

{
    "secret": "<secretKey>",
    "token": "<token>",
    "clientUid": "<eindeutigeClientId>",
    "name": "<username>"
}

Ersetze die Platzhalter mit den entsprechenden Werten.

Parameter	Platzhalter	Wert / Beschreibung
secret	<secretKey>	Dein Secret-Key (den Secret-Key findest du im Bereich „Mein Konto“).
token	<token>	Das Token, welches über das Widget generiert wurde. Es befindet sich im Input-Feld pc-token des geschützten Formulars.
clientUid	<eindeutigeClientId>	Die eindeutige Client-ID (z.B. IP-Adresse), die bereits im Widget vergeben wurde (data-pc-client-uid Attribut).
name	<username>	Der unveränderte Wert des zusätzlich geschützten Feldes (z.B. Benutzername oder E-Mail), welches mit data-pc-user markiert wurde (optional, nur mit Enterprise-Tarif). Wenn kein zusätzliches Feld geschützt wird, kann der Parameter weggelassen werden.

Wichtig

Im Header der Anfrage muss außerdem der API-Key im Feld X-API-Key hinterlegt werden.

Auswertung der Antwort

Unsere Verifikations-API gibt ein JSON zurück, welches folgende Struktur hat:

{
     "success": true|false,
     "errors": []
}

Verifizierung erfolgreich (success == true)

Wenn das Feld success den Wert true hat, war die Verifizierung erfolgreich und das Token ist gültig. Der Zugriff auf dein Formular war also berechtigt und du kannst mit der Evaluierung des Formulars fortfahren.

Verifizierung nicht erfolgreich (success == false)

Hat das Feld success hingegen den Wert false, dann war die Verifizierung nicht erfolgreich. In diesem Fall sollte die weitere Evaluierung des Formulars abgebrochen werden, da das Token nicht von POWER CAPTCHA verifiziert werden konnte.

Eine nicht erfolgreiche Verifizierung kann verschiedene Ursachen haben:

• Das Token ist ungültig (z.B. Captcha wurde nicht gelöst).
• Das Token ist abgelaufen (zu viel Zeit zwischen dem Klick auf das Widget und der Token-Verifizierung).
• Das Token wurde bereits verifiziert (eine mehrfache Verifizierung ist nicht möglich).
• Die Client-UID weicht von der Client-UID aus dem Widget (data-client-uid) ab.
• Der Wert des zusätzlich geschützten Feldes (z.B. Benutzername oder E-Mail-Adresse) weicht von dem Wert aus dem Widget (data-pc-user) ab.
• Die Verifizierungsanfrage ist falsch aufgebaut (fehlende oder ungültige Parameter).

Fehlerhafte Anfrage

Wenn die Anfrage falsch aufgebaut ist oder es einen Fehler während der Verifizierung gab, werden im Feld errors spezifische Fehler-Codes als Liste zurückgegeben. Andernfalls ist die Liste leer.

Die Fehler-Codes können auf eine ungültige Anfrage hindeuten (z.B. fehlende oder ungültige Parameter). Nachfolgend eine Beschreibung der Fehler-Codes.

Fehler-Code	Beschreibung
missing_token	Kein oder ein leeres Token im JSON.
missing_secret	Das JSON enthält keinen Secret-Key.
invalid_secret	Der Secret-Key ist ungültig oder passt nicht zum API-Key.
invalid_token	Das Token ist nicht gültig, abgelaufen oder wurde bereits verifiziert.

Beispiel mit PHP

Nachfolgend ein einfaches Beispiel mit PHP, wie das Token in deinem Backend über unsere API verifiziert werden kann. Die Platzhalter <apiKey> und <secretKey> müssen mit deinem API-Key und deinem Secret-Key ersetzt werden.

<?php
$token = $_POST['pc-token']; // Inhalt des Token-Felds (wird durch das Widget automatisch zum Formular hinzugefügt)
$clientUid = hash('sha256', $_SERVER['REMOTE_ADDR']); // eindeutige Client-ID (selber Wert wie im data-client-uid Attribut)
$username = $_POST['username']; // Unveränderter Wert des Feldes, das mit 'data-pc-user' markiert wurde (optional, nur Enterprise-Tarif)

// curl initialisieren
$curl = curl_init('https://api.power-captcha.com/pcu/v1/verify');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POST, TRUE);

// HTTP-Header setzen
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'X-API-Key: <apiKey>', // Dein API-Key
    'Content-Type: application/json'
));

// JSON-Body erzeugen
$json_body = json_encode(array(
    'secret' => '<secretKey>', // Dein Secret-Key
    'token' => $token,
    'clientUid' => $clientUid,
    'name' => $username
));

// JSON-Body als POST-Anfrage setzen
curl_setopt($curl, CURLOPT_POSTFIELDS, $json_body);

// Anfrage absenden
$response = json_decode(curl_exec($curl));
curl_close($curl);

// Antwort auswerten
if($response->success) {
    // Verifizierung erfolgreich und Token gültig
    // Hier kannst du deinen Code für die weitere Verarbeitung deines Formulars einfügen
} else {
    // Fehler bei der Verifizierung oder Captcha nicht gelöst: Evaluierung abbrechen,
    // ggf. Fehlerbehandlung hinzufügen.
}