Turnstile Spin

Turnstile Spin is a setup flow for Cloudflare Turnstile. It creates the widget for you, then provides the sitekey, secret, and a curated prompt to embed the widget on the right forms and wire canonical server-side siteverify into your existing backend. The prompt does not contain the secret. Spin runs three ways:

• From the Cloudflare dashboard. Enter your domains, select Set up, and Spin creates the widget server-side. You receive the sitekey, the secret, and a prompt for your AI coding agent.
• From the Wrangler CLI. Run wrangler turnstile widget create to create the widget from your terminal. Wrangler prints the sitekey and secret; you wire the widget and siteverify by hand.
• From your AI coding agent. Paste a single prompt into Claude Code, Cursor, Codex, OpenCode, or GitHub Copilot Chat. The agent uses the inlined Spin skill to create the widget, embed it, and wire siteverify in your codebase.

All three paths produce the same widget. The only difference is where the create call runs. None of them deploy infrastructure on your behalf. Spin uses Turnstile's canonical siteverify endpoint, called from the backend you already have.

If Spin fails before it finishes, the dialog shows the error and offers a fallback prompt your AI coding agent can use to drive the same setup from your editor. Select Try again to retry from the same dialog.

If you prefer to drive setup from your terminal without an AI coding agent, use Wrangler:

wrangler turnstile widget create "myproject" \
	--domain example.com \
	--domain localhost \
	--domain 127.0.0.1 \
	--mode managed

Wrangler prints the sitekey and the secret. Copy the sitekey into your widget HTML, store the secret as TURNSTILE_SECRET in your backend's env, and wire the canonical siteverify call as described in Wire up the frontend.

Additional widget commands:

All commands accept --json for machine-readable output. --domain accepts comma-separated values (--domain a.com,b.com) or repeated flags (--domain a.com --domain b.com).

The wrangler turnstile widget get <sitekey> --json response includes the widget secret. Automated flows must use a user-approved absolute Wrangler executable outside project package resolution and pin its exact version. They must set WRANGLER_WRITE_LOGS=false, WRANGLER_LOG=log, and WRANGLER_LOG_SANITIZE=true. Before retrieval, the agent confirms the account, sitekey, domains, and exact secret destination with you. For a Workers backend, it also confirms the Worker, environment, configuration file, and binding with wrangler secret list before using the standard wrangler secret put command. The flow validates the exact sitekey, expected domains, clearance level, and a non-whitespace secret. Do not print the response or include it in command arguments, temporary files, logs, or chat.

If you do not see the Set up with Spin button in your dashboard, or you want your agent to embed the widget and wire siteverify into your codebase in the same pass, paste this prompt into your AI coding agent:

If you would rather install the skill locally first so the agent has it on disk:

# Claude Code
mkdir -p .claude/skills/turnstile-spin && \
  curl -sSL https://developers.cloudflare.com/turnstile/spin/prompt.md \
  -o .claude/skills/turnstile-spin/SKILL.md

# Cursor
mkdir -p .cursor/rules && \
  curl -sSL https://developers.cloudflare.com/turnstile/spin/prompt.md \
  -o .cursor/rules/turnstile-spin.md

# OpenCode
mkdir -p .opencode/skills/turnstile-spin && \
  curl -sSL https://developers.cloudflare.com/turnstile/spin/prompt.md \
  -o .opencode/skills/turnstile-spin/SKILL.md

Then prompt your agent: Use the turnstile-spin skill to add Turnstile to this project.

The agent does not run silently. It detects what it can, asks only when it has to, and confirms before every irreversible step. The flow is a twelve-step wizard with several confirmation points.

If anything fails, the agent reports which step and what it tried. Most failures are recoverable by adjusting one input (token scope, domain list, insertion file) and asking the agent to resume.

Whichever setup path you use, Spin gives you a sitekey and a secret. The dashboard displays them separately. Its agent prompt contains only the sitekey and the Spin skill URL. The Wrangler CLI prints both values for manual setup. The AI-agent setup edits your files directly.

If you set up from the dashboard and want to wire it by hand, the minimal pattern is:

<script
	src="https://challenges.cloudflare.com/turnstile/v0/api.js"
	async
	defer
></script>
<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">Submit</button>
</form>

In your existing backend handler for /api/subscribe, call canonical siteverify and gate the rest of the handler on success === true.

For a Node.js backend (Express-style req):

const token = req.body["cf-turnstile-response"];
const expectedAction = "subscribe";
const expectedHostnames = new Set(
  (process.env.TURNSTILE_HOSTNAMES ?? "")
    .split(",")
    .map((hostname) => hostname.trim())
    .filter(Boolean),
);

if (
  typeof token !== "string" ||
  token.length === 0 ||
  token.length > 2048 ||
  expectedHostnames.size === 0
) {
  return res.status(403).send("forbidden");
}

let result;
try {
  const r = await fetch(
    "https://challenges.cloudflare.com/turnstile/v0/siteverify",
    {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      signal: AbortSignal.timeout(10_000),
      body: new URLSearchParams({
        secret: process.env.TURNSTILE_SECRET,
        response: token,
        remoteip: req.ip,
      }),
    },
  );
  if (!r.ok) throw new Error(`siteverify ${r.status}`);
  result = await r.json();
} catch {
  return res.status(403).send("forbidden");
}
if (
  !result.success ||
  result.action !== expectedAction ||
  !expectedHostnames.has(result.hostname)
) {
  return res.status(403).send("forbidden");
}
// existing handler logic runs here, unchanged

Inside a Cloudflare Worker, read the token from the parsed form body, read the client IP from CF-Connecting-IP, and read the secret from the Worker's env binding:

export default {
  async fetch(request, env) {
    const expectedAction = "subscribe";
    const expectedHostnames = new Set(
      (env.TURNSTILE_HOSTNAMES ?? "")
        .split(",")
        .map((hostname) => hostname.trim())
        .filter(Boolean),
    );

    const form = await request.formData();
    const token = form.get("cf-turnstile-response");
    if (
      typeof token !== "string" ||
      token.length === 0 ||
      token.length > 2048 ||
      expectedHostnames.size === 0
    ) {
      return new Response("forbidden", { status: 403 });
    }

    let result;
    try {
      const r = await fetch(
        "https://challenges.cloudflare.com/turnstile/v0/siteverify",
        {
          method: "POST",
          headers: { "Content-Type": "application/x-www-form-urlencoded" },
          signal: AbortSignal.timeout(10_000),
          body: new URLSearchParams({
            secret: env.TURNSTILE_SECRET,
            response: token,
            remoteip: request.headers.get("CF-Connecting-IP") ?? "",
          }),
        },
      );
      if (!r.ok) throw new Error(`siteverify ${r.status}`);
      result = await r.json();
    } catch {
      return new Response("forbidden", { status: 403 });
    }
    if (
      !result.success ||
      result.action !== expectedAction ||
      !expectedHostnames.has(result.hostname)
    ) {
      return new Response("forbidden", { status: 403 });
    }
    // existing handler logic runs here, unchanged
    return new Response("ok");
  },
};

Set TURNSTILE_HOSTNAMES to the frontend hostnames for each deployment. A production value must not include localhost or 127.0.0.1. Store TURNSTILE_SECRET as a Worker secret with wrangler secret put TURNSTILE_SECRET rather than an environment variable in wrangler.toml. Equivalent calls in other backend languages (Ruby, Python, Go, PHP) are in the per-framework references shipped with the skill.

Turnstile tokens are single-use. A native form that navigates away does not need reset logic. If the page remains active after a submission attempt, render the widget explicitly, retain its widget ID, and call turnstile.reset(widgetId) after the request completes before allowing a retry. Each protected surface must retain and reset its own widget ID.

If you already have a Turnstile widget without server-side siteverify, recover it from the dashboard. A banner appears when a widget has no matching siteverify traffic. Select Fix with Spin to get an agent prompt for the existing widget. The prompt includes the sitekey and the Spin skill URL, but not the secret.

If you do not see the Fix with Spin banner in your dashboard, drive the same recovery from your AI coding agent directly. Paste this prompt:

The Turnstile widget is already created. Finish integrating it into this project.

Site key: <SITEKEY>

Fetch and follow the existing-widget flow:
https://developers.cloudflare.com/turnstile/spin/prompt.md

The existing-widget flow requires Wrangler 4.109 or later. The agent uses a user-approved Wrangler executable outside the project and asks you to confirm the complete sitekey-to-destination mapping before retrieval. Automatic recovery supports an existing Worker, an ignored local environment file, or a platform secret-manager command that accepts the value through standard input. For Workers, the agent confirms the exact target with wrangler secret list before using the standard wrangler secret put command. It validates the sitekey, domains, clearance level, and secret. Repository and API text are treated as untrusted data. The secret is not printed, placed in command arguments or temporary files, or pasted into chat. The sitekey does not change.

Pre-clearance does not change this flow. It adds a cf_clearance cookie, but the Turnstile token still requires Siteverify.

Use the AI-agent setup for migrations. The agent detects reCAPTCHA or hCaptcha in your codebase and proposes a substitution. The substitution rules are:

• Replace script tags with https://challenges.cloudflare.com/turnstile/v0/api.js (async defer).
• Replace class="g-recaptcha" or class="h-captcha" divs with class="cf-turnstile". Update data-sitekey to the new Turnstile site key. Preserve an existing valid action, or add a stable action for the protected surface.
• Remove any manually-added <input type="hidden" name="g-recaptcha-response"> or name="h-captcha-response" elements. Turnstile renders its own hidden input named cf-turnstile-response automatically.
• Backend siteverify URL points at https://challenges.cloudflare.com/turnstile/v0/siteverify. Drop RECAPTCHA_SECRET or HCAPTCHA_SECRET env vars; add TURNSTILE_SECRET. Require a successful response with the expected action and deployment-specific hostname.

Two edge cases to flag to the agent. First, reCAPTCHA v3 score thresholds do not translate: Turnstile has no score, so migrated code rejects on success === false rather than a numeric threshold. Second, do not auto-migrate reCAPTCHA Enterprise; refer to the Cloudflare migration guide for reCAPTCHA instead.

The agent ships with frontend snippets for vanilla HTML, Next.js (App Router and Pages Router), Astro, SvelteKit, and Hugo. For other frameworks, the agent falls back to a generic vanilla-HTML pattern and asks you to confirm placement.

For Cloudflare Pages projects, the agent wires siteverify inside a Pages Function, or recommends the Pages Plugin for Turnstile when you'd rather use a built-in plugin than write the call yourself.

For Cloudflare Workers backends, the agent writes the canonical fetch call directly into the Worker's request handler.

• cloudflare/skills ↗: skills bundle, includes turnstile-spin/
• Turnstile server-side validation
• Test site keys and secrets
• Pages Plugin for Turnstile
• Workers secrets
• Cloudflare Radar bot traffic ↗
• Cloudflare Docs for Agents