Security guidance

HumanPass must be verified by your trusted backend. The browser widget is public and attacker-controlled, so its visual state alone is never proof.

Keep the secret server-side

• Store hp_secret_... in a secret manager or server-only environment variable.
• Never include it in HTML, browser JavaScript, mobile applications, public build arguments, source maps, logs, or error responses.
• Rotate secrets when team access changes and immediately after suspected exposure.

Verify at the protected operation

Verify the response immediately before the side effect it protects. Do not verify on one endpoint and trust an unrelated later request unless your own server creates a secure, short-lived binding.

Examples of protected side effects include:

• creating an account;
• sending a password-reset message;
• submitting a contact form;
• placing an order;
• performing a high-risk account change.

Validate context

Use expectedAction and expectedHostname with the SDK. For direct HTTP integrations, compare the returned action, hostname, sitekey, and environment yourself.

Reject mismatches. Do not silently fall back to a less specific action or hostname.

Treat responses as single-use secrets

• Submit a response promptly.
• Never persist it as a session credential.
• Never log it.
• Obtain a new response after expiry, reset, or a completed verification attempt.
• Use an idempotency key only for a bounded retry of the exact same verification request.

Fail closed

Reject or postpone the operation when:

• HumanPass returns success: false;
• the request times out;
• the response is malformed;
• expected action or hostname does not match;
• HumanPass or your own verification path is unavailable.

Give legitimate visitors a clear retry path instead of proceeding without verification.

Preserve other controls

HumanPass is an abuse-control signal, not proof of identity. Keep authentication, authorization, CSRF protection, application rate limits, input validation, fraud checks, and secure account recovery.

Browser policy

Load immutable widget versions from humanpass.valgix.com. Restrict script-src, connect-src, and worker-src with Content Security Policy. Avoid third-party proxies that can modify widget or API traffic.

Privacy-aware application design

Send remoteIp to siteverify only when it is useful and permitted by your privacy policy. Do not place personal data in site names, action names, idempotency keys, or client-visible diagnostics.