How HumanPass works

HumanPass separates public browser work from trusted server verification. A successful-looking widget is not enough: your backend must verify the response token.

Request flow

1. The widget sends the public sitekey to HumanPass from the browser’s Origin.
2. HumanPass validates the site, origin, mode, and action before issuing a challenge.
3. The widget completes the challenge and redeems it for an opaque hp_response_... token.
4. Your browser submits that response token to your backend.
5. Your backend authenticates to POST /v1/siteverify with its secret key.
6. HumanPass atomically consumes the response and returns the verified hostname, action, sitekey, environment, and verification ID.
7. Your backend compares the expected action and hostname, then accepts or rejects the protected operation.

What is bound to a response

A HumanPass response is bound to its site, environment, origin hostname, action, issue time, expiry, and protocol version. It cannot be moved safely between unrelated sites or operations.

Single-use verification

A valid response can be consumed once. A second verification normally returns timeout_or_duplicate. This prevents a captured response from approving multiple operations.

Use idempotencyKey only to make a bounded retry of the same verification request. Do not reuse one idempotency key for different responses or business operations.

Dashboard-authoritative settings

The dashboard controls the site’s presentation mode and policy. The widget loads the current public configuration after HumanPass validates the browser origin. There is intentionally no data-humanpass-mode attribute: client-side markup is not trusted to weaken the configured mode.

Fail-closed behavior

Invalid credentials, disallowed origins or actions, expired responses, duplicate responses, unavailable replay protection, and malformed requests fail verification. Your application should also fail closed when it cannot reach HumanPass, while presenting a clear retry path to the user.

HumanPass is one layer

HumanPass raises the cost of automated abuse and supplies verification evidence. It does not prove identity and should not replace:

• authentication and authorization;
• application rate limiting;
• CSRF protection;
• fraud and payment controls;
• input validation;
• account recovery safeguards.