Verify a client token¶

Warning

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¶

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`.
`400`	Necessary fields are missing in the body of the request, or the body is incorrect.
`429`	The count of the requests is exceeded. Wait the count of seconds that is given in the `Retry-After` header, then send the request again.
`500`	Unexpected error on the server.

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` or `null`	Tells if a true verification occurred. The `false` and `null` values are 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.

Warning

A response with train: true means that the request was not examined and that each transmission counts as successful. This occurs with an unknown sitekey, with a secret that does not agree, and when the protection of the sitekey is off. It also occurs with each other malfunction of the verification. In production, examine the values of sitekey and secret immediately.

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.
`invalid-input-sitekey`	The sitekey is unknown.
`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.

Examples of the response¶

Token valid:

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

Token invalid or used before:

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

Verification skipped, credentials incorrect:

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

Error response with the 400, 429, and 500 status codes:

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

Verify the credentials¶

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