Migrate from Turnstile

Replace a Cloudflare Turnstile widget and its siteverify call with AgentGate, attribute by attribute and field by field.

AgentGate's widget and server check follow the same shape as Turnstile: a script, an element with a site key inside your form, a token in a hidden field, and a server-side call that redeems it once. Most migrations change a handful of lines.

1. Create a site

Add your site in the console. You get a site key (site_…) and a backend secret (ags_…). Configure every origin that serves the form, and an action for each form: unlike Turnstile, AgentGate requires an action and checks it at validation.

2. Swap the widget

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<form method="post" action="/signup">
  <div class="cf-turnstile" data-sitekey="0x4AAA…" data-action="signup" data-theme="light"></div>
  <button>Sign up</button>
</form>

<script src="https://agentgate.example/sdk/v1/agentgate.js" async></script>
<form method="post" action="/signup">
  <div class="agentgate" data-sitekey="site_…" data-action="signup" data-mode="managed"></div>
  <button>Sign up</button>
</form>

JavaScript API:

If your page sets a CSP, replace challenges.cloudflare.com with your AgentGate endpoint in script-src and connect-src, and add worker-src blob: (details). AgentGate uses no iframe, so frame-src needs nothing.

3. Swap the server call

const form = new URLSearchParams({ secret: process.env.TURNSTILE_SECRET,
  response: body["cf-turnstile-response"], remoteip: ip, idempotency_key: opId });
const r = await fetch("https://challenges.cloudflare.com/turnstile/v0/siteverify", { method: "POST", body: form });
const v = await r.json();
if (!v.success || v.action !== "signup") return reject(v["error-codes"]);

const r = await fetch("https://agentgate.example/v1/siteverify", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer " + process.env.AGENTGATE_SECRET },
  body: JSON.stringify({ token: body.agentgate_token, expectedAction: "signup",
    expectedOrigin: "https://app.example.com", requestId: opId }),
});
const v = await r.json();
if (!v.success) return reject(v.error);

4. Differences to plan for

• Token lifetime. Two minutes by default (Turnstile: five). Verify at submit time; the widget already does.
• Pre-clearance. Turnstile's pre-clearance cookie corresponds to AgentGate clearances, accepted by the AgentGate gateway on clearance actions.
• Monitor mode. New sites start in monitor mode: every valid token passes and wouldDecision shows what enforce would have done. Switch to enforce when you are satisfied.
• Testing keys. Turnstile's dummy keys map to site_test_always_pass, site_test_always_fail, site_test_force_interactive and the secrets ags_test_always_pass, ags_test_always_fail, ags_test_token_spent (Testing).
• Agents. AgentGate also admits AI agents that sign their requests; see Signed agents.