Verification fundamentals
Why CAPTCHA validation belongs on the server
Understand the trust boundary between a widget and a protected endpoint, and test missing, rejected, and unavailable verification outcomes.
By the easycaptcha team · Published
A widget can display completion and supply a response value, but the protected endpoint must decide whether to perform the action. If it trusts a client flag such as verified: true, a direct caller can provide that flag without completing the intended challenge.
The server’s role
A provider’s verification API checks the submitted proof using server-owned configuration. hCaptcha’s server integration reference describes that boundary. Keep site-owner secrets out of frontend code.
Validate before the protected operation
Map where messages, accounts, reservations, or payment attempts are actually created. Enforce verification there, including alternate client routes. A challenge in the main HTML form does not cover an API path that performs the same operation without a proof.
Your endpoint should reject missing or malformed input, require successful verification according to policy, and preserve an understandable error when the provider cannot serve the request. Authentication and business eligibility remain separate checks.
Bind configuration on the server
The public sitekey and provider selection are not arbitrary privileges the caller can grant itself. Use trusted configuration for the expected flow. If several providers are supported, define which proofs satisfy the operation server-side rather than accepting whichever shape the caller prefers.
Do not expose a detached verification success endpoint that callers can treat as a reusable permission if that is not your intended architecture. The proof and action need an explicit lifecycle.
Test direct requests
Include an omitted proof, a made-up proof, a rejected provider response, and an unavailable dependency. Verify that no protected work occurs. Then verify that a legitimate visitor can obtain a new proof and retry without losing appropriate form content.
Read fail-closed behavior for unavailable providers, proof expiration for freshness, and browser testing for separating deterministic application checks from live provider checks.
Frequently asked questions
Why must CAPTCHA be verified on the server?
Browser input can be changed or omitted. The protected server operation must verify the supplied proof against trusted configuration before proceeding.
Should I trust a frontend success callback?
Treat it as an interaction signal, not authorization. The server still needs to verify the proof and validate the requested operation.
How can easycaptcha fit into my integration tests?
Use the documented recognition or token API for the hCaptcha stage, preserve task IDs, and inspect terminal results. Measure verifier acceptance and application completion separately from job completion.