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

SKILL.md · 24000

eset(widgetId)` after the request completes before allowing a retry. Each protected surface must retain and reset its own widget ID. The framework references show the appropriate lifecycle hook.

Migrating from another CAPTCHA

During the Step 6 codebase scan, also look for existing reCAPTCHA or hCaptcha. If found, switch Step 7 to a migration plan.

Detection signals:

  • reCAPTCHA: https://www.google.com/recaptcha/api.js, class="g-recaptcha", data-sitekey="6L...", backend POST to /recaptcha/api/siteverify
  • hCaptcha: https://js.hcaptcha.com/1/api.js, class="h-captcha", backend POST to https://hcaptcha.com/siteverify

Substitution:

  • Replace script tags with https://challenges.cloudflare.com/turnstile/v0/api.js (async defer).
  • Replace class="g-recaptcha" / class="h-captcha" divs with class="cf-turnstile", update data-sitekey to the new Turnstile sitekey, and set a meaningful data-action for the protected surface.
  • Token field changes from g-recaptcha-response to cf-turnstile-response.
  • Backend siteverify URL points at https://challenges.cloudflare.com/turnstile/v0/siteverify. Drop RECAPTCHA_SECRET / HCAPTCHA_SECRET env vars; add TURNSTILE_SECRET.

Edge cases to surface to the user:

  • reCAPTCHA v3 score thresholds. Turnstile has no score. Tell the user explicitly that migrated code will reject on success === false.
  • reCAPTCHA Enterprise. Don't auto-migrate. Point at developers.cloudflare.com/turnstile/migration/recaptcha/.
  • Custom action= values. Preserve any valid custom action the user passed to grecaptcha.execute as data-action on the widget. Otherwise, use the stable action assigned in Step 7. In both cases, validate the returned action in the backend.

Edge cases

| Situation | Action | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Account enumeration is unavailable | Ask the user for the account ID and export CLOUDFLARE_ACCOUNT_ID, or obtain approval for canonical absolute WRANGLER_BIN and exact WRANGLER_VERSION. Do not install or run a project-local Wrangler. | | Multiple Cloudflare accounts | scripts/auth-probe.sh returns all accounts; ask the user to choose, export CLOUDFLARE_ACCOUNT_ID | | Cloudflare Pages project | Wire siteverify inside a Pages Function (or the equivalent for your framework). The Pages Plugin at developers.cloudflare.com/pages/functions/plugins/turnstile is a shortcut. | | Cloudflare Workers backend | Use the canonical fetch idiom from Step 9 inside the Worker's request handler. fetch to challenges.cloudflare.com works the same way it does in Node. | | EXPECTED_HOSTNAME mismatch | Update widget domains via PUT, not PATCH (PATCH returns 10405 Method not allowed): curl -X PUT .../widgets/$SITEKEY -d '{"name":"...","mode":"managed","domains":[...]}' | | Token expired mid-flow | Stop, re-run scripts/auth-probe.sh, prompt for fresh credentials | | Validation returns invalid-input-secret | The secret didn't reach the backend. Re-check TURNSTILE_SECRET in the customer's env / secret manager. If it's a Workers backend, run wrangler secret list to confirm the secret is bound to the right script. | | Validation returns invalid-input-response | Expected for a dummy probe token; that means the secret IS valid. validate.sh treats this as success. |

Skill feedback

If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.