Verification fundamentals
CAPTCHA hostname, sitekey, and action checks
Bind verification to the application flow your server expects instead of accepting any successful-looking proof from an unrelated context.
By the easycaptcha team · Published
A provider’s successful response is useful only within the policy of the protected operation. Your application may need to enforce a configured sitekey, allowed hostname, or expected action depending on the provider. Those values should come from server-owned policy, not from the caller’s preferred configuration.
Verification context
Do not treat similarly named fields across providers as identical. Read the exact verification reference for the product and mode you deploy.
Separate three different identities
| Value | What it describes |
|---|---|
| Sitekey | Public challenge configuration |
| Hostname | Application origin or context reported by the provider |
| Action | Named flow where the provider supports it |
A customer API key has a fourth role: authorizing work in the solving service. None of these values should be casually substituted for another in an integration adapter.
Define the expected flow centrally
Keep a mapping from protected operations to required provider configuration. Review login, signup, checkout, and recovery separately. A caller should not obtain weaker enforcement by choosing another key or omitting an expected action.
When your application supports several environments, keep test and production values distinct. Check the deployment’s actual hostname rather than only a localhost fixture.
Test mismatches deliberately
Include a proof with the wrong context, a missing proof, malformed provider output, and a normal valid case. Confirm that rejection happens before protected work. Preserve a clear retry path when the visitor needs fresh verification.
For Turnstile, consult the server-validation documentation. For hCaptcha, use the developer reference for the expected sitekey verification parameter. Keep operational records limited to configuration identifiers and error stages rather than proof contents.
Sitekey segmentation describes how context affects measurements. Proof lifecycle covers freshness, which is a separate condition from matching the intended flow.
Frequently asked questions
Is a successful verification response enough to authorize an action?
The application must also check the context required by its provider integration, such as the expected domain or action, and its own authorization rules.
Where should expected verification settings come from?
Use trusted server configuration. A request from the browser should not define the policy against which its own proof is checked.
How do I start using the easycaptcha API?
Create an account and get an API key, then follow the getting-started guide. Submit recognition or token tasks through raw HTTP or the typed Python and JavaScript SDKs.