Skip to content
Shield · Turnstile migration

Shield

Migrating from Turnstile

Shield was designed to be a drop-in replacement: the same sitekey/secret model, and a siteverify response that matches Turnstile's field for field. Most migrations are a URL swap and a pair of new keys.

On this page6 sections

1. Create a Shield widget#

In the console, create a widget matching your Turnstile configuration: the same hostnames and the equivalent mode (Turnstile’s Managed/Non-Interactive/Invisible map one-to-one to Shield’s). Note your new sitekey and secret.

2. Swap the client snippet#

HTML
<!-- Before: Turnstile -->
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" defer></script>
<div class="cf-turnstile" data-sitekey="0x4AAA..."></div>
HTML
<!-- After: Shield -->
<script src="https://shield.edge.network/api.js" defer></script>
<div class="edge-shield" data-sitekey="es_..." data-compat="turnstile"></div>

Shield’s callbacks (data-callback, data-error-callback, data-expired-callback) follow the same conventions as Turnstile’s.

3. Swap the siteverify URL and secret#

JavaScript
// Before
const url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'

// After: the response shape is identical (plus a "score" field)
const url = 'https://shield.edge.network/siteverify'

Replace the secret with your es_secret_… key. The response contains the same fields (success, challenge_ts, hostname, error-codes) with familiar error code names (timeout-or-duplicate, invalid-input-secret, etc.), so existing error handling carries over.

4. Optional: use the score#

Turnstile gives you pass/fail. Shield’s responses also carry a score (1–100). Once migrated, you can add graduated handling: auto-approve high scores, step up uncertain ones, and route or block automation. See Server-side validation.

Differences to be aware of#

  • Key formats: sitekeys are es_… and secrets es_secret_…. If you validate key formats anywhere, update the patterns.
  • Hidden input: the default is edge-shield-response. Use data-compat="turnstile" during transition, then switch your server to the new field name at leisure.
  • Privacy: Shield stores no per-visitor data and sets no cookies. If your privacy policy documented Turnstile’s cookies, you can simplify it.
  • Idempotency: like Turnstile, tokens are single-use and expire after 5 minutes.

Next steps

Something unclear or out of date? Tell us

View as Markdown Get support