HumanProof Docs | Widget, site keys, and server validation

Docs section

Siteverify

Siteverify must run on your server. Never render the backend secret into client-side code.

Call this endpoint after the browser widget has filled the hidden token field and before you continue with login, registration, checkout, contact, or any other protected action.

Request

POST https://humanproof.eu/api/siteverify
Content-Type: application/json
Accept: application/json

{
  "secret": "YOUR_BACKEND_SECRET",
  "response": "TOKEN_FROM_FORM"
}

Request fields

Field	Required	Description
secret	Yes	The project backend secret. Store it server-side only and rotate it from the project settings if exposed.
response	Yes	The token from the hidden form field. The default field name is humanproof-token unless data-hidden-field-name changes it.

Response body

Treat success: true as the only passing result. Any missing success field, false value, validation error, non-2xx status, or network failure must block the protected action.

{
  "success": true
}

{
  "success": false,
  "error": "Token not found"
}

Field	Type	Description
success	boolean	true only when the token is valid and accepted.
error	string\|null	Present on known failure responses. The value is intended for logging and support, not for trusting client-side decisions.

Status codes

Status	Meaning	Recommended handling
200	Verification completed.	Read success. Continue only when success is true.
401	Backend secret is invalid or revoked.	Block the action and check the configured backend secret.
402	Billing status blocks verification.	Block the action and resolve billing in HumanProof.
403	Project is suspended.	Block the action and reactivate the project if expected.
422	Request validation failed, project engine is not configured, or public test keys are unavailable.	Block the action and inspect the request fields or project setup.
429	Rate limit exceeded.	Block or retry later. Do not bypass verification.
5xx	HumanProof or the challenge backend is temporarily unavailable.	Fail closed for sensitive actions, log the incident, and retry later if appropriate.

Token lifecycle