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.
1. Create a Shield Widget
In the control panel, create a widget matching your Turnstile configuration — 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
<!-- Before: Turnstile -->
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" defer></script>
<div class="cf-turnstile" data-sitekey="0x4AAA..."></div><!-- After: Shield -->
<script src="https://shield.edge.network/api.js" defer></script>
<div class="edge-shield" data-sitekey="es_..." data-compat="turnstile"></div>Compatibility mode
data-compat="turnstile"
makes the widget also populate a
cf-turnstile-response
hidden input, so server code that reads Turnstile's field name keeps working without
changes during the transition.
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
// 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 additionally 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 differ: sitekeys are es_…and secretses_secret_…. If you validate key formats anywhere, update the patterns. -
The default hidden input is edge-shield-response— usedata-compat="turnstile"during transition, then switch your server to the new field name at leisure. -
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.