Register a Turnstile widget in the Cloudflare dashboard under Turnstile; choose a widget type (Managed, Non-Interactive, or Invisible) and note your Site Key and Secret Key.
Embed the Turnstile widget on the client side by loading https://challenges.cloudflare.com/turnstile/v0/api.js and adding a div with class cf-turnstile and data-sitekey=YOUR_SITE_KEY; the widget renders automatically and populates a hidden input named cf-turnstile-response with a token.
When your form is submitted, send the cf-turnstile-response token to your backend; never validate tokens in client-side code.
On your backend, make a POST request to https://challenges.cloudflare.com/turnstile/v0/siteverify with a URL-encoded or JSON body containing secret=YOUR_SECRET_KEY and response=TOKEN_FROM_CLIENT; optionally include remoteip for additional signal.
Parse the JSON response: if success is true, allow the action; if false, inspect the error-codes array and reject the request. Tokens expire after 300 seconds and can only be validated once—do not cache or reuse tokens.
For Cloudflare Workers deployments, use the Turnstile Workers integration which can call siteverify internally using the secret from an environment variable, avoiding exposure of the secret in client-reachable code.
Known gotchas
The siteverify endpoint only accepts POST requests; GET requests are rejected. Send parameters as application/x-www-form-urlencoded or application/json—do not mix formats in the same request.
The Secret Key must never appear in client-side JavaScript or HTML; it authenticates your server to Cloudflare, and exposure allows anyone to forge validation responses.
In test environments, Cloudflare provides always-pass (1x0000000000000000000000000000000AA) and always-fail (2x0000000000000000000000000000000AA) site keys; use them in CI pipelines to avoid real widget interactions without hardcoding production keys.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp