Token verification via the Verification API

Our widget automatically adds an hidden input field pc-token to your form. This field contains a token you can verify in your backend.

This allows you to ensure that access has been checked and is authorized (e.g. if the captcha has been solved properly).

Request to the Verification API

The verification is done via our API (https://api.power-captcha.com/pcu/v1/verify). The following parameters must be sent to this endpoint as a JSON body via POST:

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

Replace the placeholders with the appropriate values.

Parameter	Placeholder	Value / Description
secret	<secretKey>	Your secret key (you can find the secret key in the "My account" section).
token	<token>	The token that was generated via the widget. It is located in the input field pc-token of the protected form.
clientUid	<uniqueClientId>	The unique client ID (e.g. IP address) that has already been assigned in the widget (data-pc-client-uid attribute).
name	<username>	The unchanged value of the additionally protected field (e.g. user name or email), which was marked with data-pc-user (optional, only with Enterprise license). If no additional field is protected, the parameter can be omitted.

Important

The API key must also be included in the request header in the X-API-Key field.

Evaluating the response

Our Verification API returns a JSON with the following structure:

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

Verification successful (success == true)

If the success field has the value true, the verification was successful and the token is valid. This means that access to your form was authorized and you can continue with the evaluation of the form.

Verification not successful (success == false)

In contrast, if the success field has the value false, then the verification was not successful. In this case, further evaluation of the form should be canceled, since the token was not verified by POWER CAPTCHA.

An unsuccessful verification can have several causes:

• The token is invalid (e.g. captcha was not solved).
• The token is expired (too much time between clicking on the widget and the token verification).
• The token has already been verified (multiple verifications are not possible).
• The client UID differs from the client UID of the widget (data-client-uid).
• The value of the additionally protected field (e.g. user name or e-mail address) differs from the value of the widget (data-pc-user).
• The verification request is invalid (missing or invalid parameters).

Failed request

If the request is invalid or the verification failed, an error code is returned in the errors field as a list. Otherwise the list is empty.

The error codes could indicate an invalid request (e.g. missing or invalid parameters). Below is a description of the error codes.

Error code	Description
missing_token	Missing or empty token in the JSON.
missing_secret	The JSON does not contain a secret key.
invalid_secret	The secret key is invalid or does not correspond to the API key.
invalid_token	The token is not valid, expired or has already been verified.

Example with PHP

Below is a simple example with PHP showing how to verify the token in your backend via our API. The placeholders <apiKey> and <secretKey> must be replaced with your API key and your secret Key.

<?php
$token = $_POST['pc-token']; // Token field value (the field was automatically added to the form by the widget)
$clientUid = hash('sha256', $_SERVER['REMOTE_ADDR']); // Unique client ID (same value as in the data-client-uid attribute)
$username = $_POST['username']; // Unchanged value of the field which was marked with ‘data-pc-user’ (optional, Enterprise license only)

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

// Set HTTP header
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'X-API-Key: <apiKey>', // Your API key
    'Content-Type: application/json'
));

// Generate JSON body
$json_body = json_encode(array(
    'secret' => '<secretKey>', // Your secret key
    'token' => $token,
    'clientUid' => $clientUid,
    'name' => $username
));

// Set JSON body as POST request
curl_setopt($curl, CURLOPT_POSTFIELDS, $json_body);

// Send request
$response = json_decode(curl_exec($curl));
curl_close($curl);

// Evaluate response
if($response->success) {
    // Verification successful, token is valid
    // Insert your code for further evaluation of your form here
} else {
    // Error during verification or captcha not solved: Cancel the evaluation,
    // and add error handling if necessary.
}