Verify a client token

Attention

Call the endpoint only from your server. The secret stays on the server and is not permitted in the source code of the page.

Send a POST request to the /verify endpoint at https://api.eu-captcha.eu/v1.

Description

The endpoint examines the proof-of-work token that verify.js made in the browser of the visitor. The verification finds if the calculations were done correctly, if the token was not used before, and if the sitekey and the secret are valid.

The success field of the response names the result of the verification. Always also examine the train field. See the description of the field in Response fields.

The endpoint does not need an authorization in a header. The authentication occurs with the secret field in the body of the request.

Request

Send the body as JSON with the Content-Type: application/json header. The body of the request contains these fields:

Field	Type	Necessary	Description
`sitekey`	`string`	yes	Public sitekey of the domain that the widget is embedded in. The value is shown in the Details view of the sitekey.
`secret`	`string`	yes	Secret that belongs to the sitekey. The value is shown in the Details view of the sitekey and stays on the server.
`client_ip`	`string`	yes	IPv4 or IPv6 address of the visitor. Send the address of the visitor, not the address of a proxy or a CDN in front of it. To get it, examine the `X-Forwarded-For` or `X-Client-IP` headers.
`client_token`	`string`	yes	Token from `verify.js`. The value comes to your server in the `eu-captcha-response` form field. The value is empty if the widget did not complete, for example when JavaScript is off.
`client_user_agent`	`string`	yes	`User-Agent` header of the request of the visitor. The value identifies the type of the client if no token was calculated.

Note

Always send the client_token field, also with an empty value. From incomplete and empty tokens, the service learns across all verifications, also the failed ones, and thus detects attacks more accurately.

See Details view.

Example

Body of the request:

{
  "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"
}

Responses

The endpoint supplies these status codes:

Status code	Description
`200`	Result of the verification. Examine `success` and `train`.
`500`	Unexpected error on the server. The response does not contain a JSON body.

Missing or incorrect fields do not cause a separate status code. The endpoint answers with the 200 status code, sets success to false, and names the cause in the error-codes field.

Response fields

The response with the 200 status code contains these fields:

Field	Type	Description
`success`	`boolean`	`true` if the token passed the verification, if not `false`. Always also examine the `train` field, because `success` gets the `true` value when `train` is `true`.
`train`	`boolean`	Tells if a true verification occurred. The field is available in each response. The `false` value is the usual operation. The `true` value is a verification that was skipped.
`error-codes`	`array`	Available only with `success: false`. Names the causes of the failure.

Attention

A response with train: true means that the request was not examined and that each transmission counts as successful. This occurs when the protection of the sitekey is off in the Configuration view. An unknown sitekey and a secret that does not agree cause success: false with the invalid-input-sitekey or invalid-input-secret error code.

Attention

For a sitekey with an expired trial period, the endpoint answers with success: true without a verification. The train field stays false. See Trial period expired.

Error codes

The error-codes field contains these values. The format agrees with reCAPTCHA, hCaptcha, and Turnstile.

Value	Meaning
`invalid-input-secret`	The secret does not agree with the sitekey, is empty, or is longer than 255 characters.
`invalid-input-sitekey`	The sitekey is unknown, empty, or longer than 255 characters.
`invalid-input-response`	The `client_token` field was available, but it did not contain a valid proof. The value was incorrect, not decodable, unsolved, or empty.
`timeout-or-duplicate`	The token was used before, or the challenge is expired. Each token is valid one time.
`missing-input-secret`	The `secret` field is missing or is not a string.
`missing-input-sitekey`	The `sitekey` field is missing or is not a string.
`missing-input-response`	The `client_token` field is missing or is not a string. An empty string counts as available and causes `invalid-input-response`.
`missing-input-remoteip`	The `client_ip` field is missing or is not a string.
`bad-request`	The body of the request could not be read as JSON. The `Content-Type` header was missing or was not `application/json`, or the body was empty or not valid JSON.

Examples of the response

Token valid:

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

Token invalid:

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

Verification skipped, protection of the sitekey off:

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

Sitekey unknown:

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

Verify the credentials

To examine the sitekey and the secret without a token, see Verify the sitekey and the secret.