AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

turnstile-spin

Set up, repair, or migrate to Cloudflare Turnstile bot verification in an existing frontend and backend, including server-side Siteverify.

Original source
cloudflare
License
Apache-2.0
Pinned revision
e44f580f9c4fa3bf268e284ae7706c7954ba31fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read cloudflare--turnstile-spin at revision e44f580f9c4fa3bf268e284ae7706c7954ba31fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 10

references/vanilla-html.md

Vanilla HTML

For static sites or any project without a JS framework. The widget renders client-side; the form submits to whatever backend handles your form (a Node/PHP/Ruby/Go server, a Cloudflare Worker, a Pages Function, a third-party form host that supports server-side hooks, etc.).

<!doctype html>
<html>
	<head>
		<script
			src="https://challenges.cloudflare.com/turnstile/v0/api.js"
			async
			defer
		></script>
	</head>
	<body>
		<form action="/api/subscribe" method="POST">
			<input name="email" type="email" required />
			<div
				class="cf-turnstile"
				data-sitekey="YOUR_SITEKEY"
				data-action="subscribe"
			></div>
			<button type="submit">Subscribe</button>
		</form>
	</body>
</html>

When the form submits, the browser includes cf-turnstile-response automatically. Your backend reads it and calls canonical siteverify.

Backend (any language)

Add this to your existing /api/subscribe handler before the rest of its logic:

// Node / fetch idiom
const expectedHostnames = new Set(
	(process.env.TURNSTILE_HOSTNAMES ?? '')
		.split(',')
		.map((h) => h.trim())
		.filter(Boolean),
);
if (expectedHostnames.size === 0) return res.status(403).end();

const token = req.body['cf-turnstile-response'];
const r = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
	method: 'POST',
	headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
	body: new URLSearchParams({
		secret: process.env.TURNSTILE_SECRET,
		response: token,
		remoteip: req.ip,
	}),
});
const result = await r.json();
if (
	r.ok !== true ||
	result.success !== true ||
	result.action !== 'subscribe' ||
	!expectedHostnames.has(result.hostname)
) {
	return res.status(403).end();
}
// existing handler logic runs here

Equivalent calls in other backend languages (each also compares result.hostname to a TURNSTILE_HOSTNAMES allowlist):

# Ruby
require 'net/http'; require 'uri'; require 'json'; require 'set'
expected_hostnames = (ENV['TURNSTILE_HOSTNAMES'] || '').split(',').map(&:strip).reject(&:empty?).to_set
halt 403 if expected_hostnames.empty?
res = Net::HTTP.post_form(URI('https://challenges.cloudflare.com/turnstile/v0/siteverify'),
  secret: ENV['TURNSTILE_SECRET'], response: params['cf-turnstile-response'], remoteip: request.ip)
result = JSON.parse(res.body)
halt 403 unless res.is_a?(Net::HTTPSuccess) && result['success'] == true && result['action'] == 'subscribe' && expected_hostnames.include?(result['hostname'])
# Python (requests)
expected_hostnames = {h.strip() for h in os.environ.get('TURNSTILE_HOSTNAMES', '').split(',') if h.strip()}
if not expected_hostnames:
    return '', 403
r = requests.post('https://challenges.cloudflare.com/turnstile/v0/siteverify',
    data={'secret': os.environ['TURNSTILE_SECRET'],
          'response': form['cf-turnstile-response'],
          'remoteip': request.remote_addr})
result = r.json()
if (not r.ok or result.get('success') is not True or result.get('action') != 'subscribe'
        or result.get('hostname') not in expected_hostnames):
    return '', 403

subscribe is the stable action for this surface. Preserve an existing custom migration action and compare the returned action to the same value. Siteverify is mandatory for every widget mode, including pre-clearance. Set TURNSTILE_HOSTNAMES to the deployment-specific frontend hostnames; a production value must not include localhost or 127.0.0.1.

Variant: AJAX submit instead of form action

For an AJAX flow, replace the native form and API script with explicit rendering. Keep this surface's widget ID and reset it in finally, which covers network, JSON, validation, and server failures as well as successful same-page completion.

<form id="subscribe-form">
	<input name="email" type="email" required />
	<div id="subscribe-turnstile"></div>
	<button type="submit">Subscribe</button>
</form>
<script>
	let subscribeWidgetId;

	window.onSubscribeTurnstileLoad = () => {
		subscribeWidgetId = window.turnstile.render("#subscribe-turnstile", {
			sitekey: "YOUR_SITEKEY",
			action: "subscribe",
		});
	};

	document.getElementById("subscribe-form").addEventListener("submit", async (event) => {
		event.preventDefault();
		try {
			const res = await fetch("/api/subscribe", {
				method: "POST",
				body: new FormData(event.currentTarget),
			});
			const json = await res.json();
			if (!res.ok || json.ok !== true) throw new Error("Submission failed");
			// proceed
		} catch {
			// surface the error
		} finally {
			if (subscribeWidgetId !== undefined) {
				window.turnstile.reset(subscribeWidgetId);
			}
		}
	});
</script>
<script
	src="https://challenges.cloudflare.com/turnstile/v0/api.js?onload=onSubscribeTurnstileLoad&render=explicit"
	async
	defer
></script>

No backend?

If your project is pure-static (no server-side handler — just HTML served from a CDN), Spin doesn't apply. Siteverify is server-side by design. Options:

  • Add a Cloudflare Pages Function (functions/api/subscribe.js) to host the siteverify call.
  • Deploy a tiny Cloudflare Worker that does siteverify against your existing form host.
  • Use a third-party form host that exposes a server-side webhook where you can wire siteverify.

Substitutions

| Placeholder | Replace with | | ------------------- | -------------------------------------------------------------------- | | YOUR_SITEKEY | The widget site key from Step 8 | | /api/subscribe | The path to your existing form-handling endpoint | | TURNSTILE_SECRET | Env-var name. Value is the secret captured in Step 8, kept off disk. |