iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To solve Cloudflare Turnstile integration problems, make sure the widget is configured for the right hostname, render it where the protected action occurs, and validate its token on your server with Cloudflare’s Siteverify API. A completed browser challenge alone does not prove that a request is valid. Turnstile can be used on sites that are not proxied through Cloudflare.
How the Turnstile integration works
A Turnstile widget uses a public sitekey in the browser and a private secret key on your server. The browser widget produces a token; your application sends that token to its backend, which calls Siteverify. Only after validation should the backend allow the protected action, such as submitting a form or creating an account. Cloudflare’s getting-started guide emphasizes that embedding the widget and validating its token on the server are both required.
Keep the secret key out of page source, client-side JavaScript, and browser requests. The browser should send the token to your backend; the backend, holding the secret, should be the only part of your application that calls Siteverify. Cloudflare documents the validation flow and response in its server-side validation guide.
Set up and render a widget
- Create a widget in the Cloudflare dashboard. Set its allowed hostnames, mode, and appearance, then copy its sitekey and secret key. The sitekey is for the page; store the secret in secure server-side configuration. See Turnstile’s setup guide and widget configuration documentation.
- Load the widget on the page containing the protected action. With implicit rendering, Turnstile scans for an element with the
cf-turnstileclass. Explicit rendering lets your JavaScript choose when and where to create the widget, which is useful when the page controls its lifecycle. Configuration details are in client-side rendering documentation. - Choose when verification begins. Automatic execution starts on page load. Manual execution lets your application call
turnstile.execute()at a chosen point, such as after a user action. Choose the mode that fits the flow rather than assuming the challenge must start immediately. - Choose how the token reaches your backend. By default, the widget adds a hidden form field named
cf-turnstile-response. You can rename or disable this field if your submission flow handles the token another way. In either case, send the token to your backend along with the protected request. - Allow the widget to load. If your Content Security Policy restricts external resources, allow the
challenges.cloudflare.comorigin where applicable. Configure secrets through a secure backend setting rather than embedding them in the page.
Choose the rendering and interaction options
| Choice | Use it when | What to account for |
|---|---|---|
| Implicit rendering | A static page should display the widget as soon as it loads. | Turnstile scans for an element with the cf-turnstile class. |
| Explicit rendering | Your JavaScript needs to control when or where the widget is created. | Your code must manage the widget lifecycle. |
| Automatic execution | Verification should begin on page load. | This is the default execution behavior. |
| Manual execution | Verification should begin at a chosen point in the user flow. | Call turnstile.execute() when appropriate. |
| Managed, non-interactive, or invisible mode | You need to choose a particular user interaction experience. | Configure the mode per widget in the dashboard; the appropriate choice depends on the application’s experience requirements. |
| Default hidden form field | A standard HTML form can submit the token with its other fields. | The default field is cf-turnstile-response; it can be renamed or disabled. |
| Custom token handling | Your application has a custom submission flow. | Ensure the token still reaches the backend that performs Siteverify validation. |
Validate every token on the server
For each protected submission, have your backend send the token to Cloudflare’s Siteverify API with the secret key. Do not accept a request merely because the widget appeared to complete successfully in the browser. Cloudflare describes the request and response fields in its Siteverify documentation.
#1 Best Overall
- Check that Siteverify reports success before performing the protected action.
- Where your widget configuration and application policy use them, verify response details such as hostname and action against the expected values.
- Use HTTPS and set a timeout for the validation request. Decide how the application should behave if Cloudflare’s API is unavailable; do not silently treat an API failure as a valid token.
- Log enough context to diagnose validation failures, but never log the secret key.
- Account for the documented token limit: Cloudflare’s getting-started guide says a token can be up to 2,048 characters. Treat that as an implementation limit, not an efficacy measure.
Handle token expiry, retries, and duplicate submissions
Turnstile tokens expire after five minutes and can be redeemed only once. A delayed submission, retry that reuses the previous token, or duplicate request can therefore fail validation. When a user retries, arrange for a fresh token and submit that token with the new attempt. Cloudflare documents token behavior in its client-side documentation and Turnstile analytics documentation.
Test with predictable credentials
Automated browsers may be detected as bots, which can make tests unreliable if they depend on ordinary challenge outcomes. Cloudflare provides dummy test sitekeys and matching test secrets for predictable pass, fail, interactive, and already-spent-token scenarios. Use the matching test credentials in non-production environments; dummy tokens do not validate with production secrets. See Cloudflare’s testing guide.
Keep test and production credentials separate in application configuration so a test secret is not used in a live deployment and a production secret is not exposed to automated test environments.
Free tools Windows power users keep installed
One-click scans. No signup required.
Diagnose common Turnstile errors
Start with the displayed error code, then check the matching configuration or environment. Cloudflare’s client-side errors guide provides current troubleshooting details.
| Error code | What to check |
|---|---|
110100 or 110110 |
Verify the sitekey and widget configuration in the dashboard. |
110200 |
Authorize the current domain in Hostname Management. This is a sitekey domain mismatch. |
110600 or 110620 |
Check the visitor’s clock and interaction timing. Retry or reset the interaction when appropriate. |
200100 |
Inspect the visitor’s clock and whether an intermediary cached the challenge. |
200500 |
Check whether challenges.cloudflare.com is blocked or cannot load. |
400070 |
Check the dashboard: the sitekey is disabled. |
Generic 300* or 600* |
These are broad challenge-failure categories, not one established root cause. Use Cloudflare’s current troubleshooting guidance and the specific context you logged. |
Use the widget’s error callback to give visitors a useful recovery path, such as retrying the challenge, rather than leaving the protected form in an unexplained failed state. For server-side failures, apply the timeout and failure behavior you defined for Siteverify requests.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What Turnstile Spin does—and does not do
Cloudflare’s Turnstile Spin setup flow can create a widget and provide a prompt for embedding it and connecting Siteverify to an existing backend. It does not deploy infrastructure on your behalf. Follow the Turnstile Spin documentation, validate the deployment-specific hostname returned by Siteverify, and do not allow local hostnames in production.
Quick Recap
Rank #4
- Made in USA - Proudly produced in Ohio by a Veteran-owned business
- Comprehensive Coverage: This BookFactory log book includes essential fields such as post/shift, time of change, date, weather conditions, and a designated space for detailed notes. This ensures that all relevant information is captured and easily accessible.
- Sturdy Cover: The trans-lux cover protects the log book from wear and tear, ensuring its longevity and maintaining the integrity of your recorded data.
- Essential Security Tool: This log book is an indispensable tool for any organization that values security and accountability. It helps to prevent misunderstandings, improve communication, and ensure a smooth transition between shifts.
- Wire-O with Trans-lux cover, 100 Pages, Dimensions 8.5" x 11" - (Security-Pass-Down) Reorder SKU: LOG-100-7CW-PP(Security-Pass-Down)
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
