Migrating from Cloudflare Turnstile

This guide shows how to migrate from Cloudflare Turnstile to ALTCHA Sentinel, a self-hosted, privacy-friendly CAPTCHA alternative that doesn’t rely on external services or user tracking.

Key Differences

Feature	Turnstile	ALTCHA
Challenge Type	Frictionless	Frictionless or code challenge
Implementation	Requires Cloudflare service	Self-hosted
Accessibility	Generally accessible	WCAG compliant, screen-reader friendly
Privacy	Cloudflare logs and tracks data	No tracking, privacy-focused
Compliance	Varies by usage and region	GDPR, CCPA, HIPAA, CPPA, LGPD, DPDPA, PIPL compliant
Verification	Server-to-Turnstile API call	Fast, local cryptographic verification
Limit	< 1,000,000 / month	Unlimited

Implementation Comparison

Cloudflare Turnstile (Previous Implementation)

Frontend:

<script
  src="https://challenges.cloudflare.com/turnstile/v0/api.js"
  async
  defer
></script>
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>

Backend (Node.js example):

const token = req.body["cf-turnstile-response"];
const secret = "YOUR_SECRET_KEY";

const resp = await fetch(
  "https://challenges.cloudflare.com/turnstile/v0/siteverify",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      secret,
      response: token,
      remoteip: req.ip,
    }),
  }
);

const verification = await resp.json();

if (!verification.success) {
  throw new Error("Turnstile verification failed");
}

ALTCHA Sentinel (New Implementation)

Frontend:

Import the ALTCHA widget:

import "altcha";

Then include the widget in your form:

<altcha-widget
  challengeurl="https://sentinel.example.com/v1/challenge?apiKey={YOUR_API_KEY}"
></altcha-widget>

Backend (Node.js example):

For supported environments, see Libraries and Plugins. Currently supported environments include TypeScript, Go, Python, Java, Elixir, PHP, and Ruby.

If the library is not available in your environment, you can use the POST /v1/verify/signature endpoint to verify the payload.

verify.js

import { verifyServerSignature } from "altcha-lib";

// The Base64-encoded payload received from the Widget upon submission
const payload = req.body["altcha"];

// Use the secret from your Sentinel App for the API key used in the challenge
const apiKeySecret = "sec_...";

// Verify the payload
const { verified } = await verifyServerSignature(payload, apiKeySecret);

if (!verified) {
  throw new Error("ALTCHA verification failed");
}

For more details, refer to the Server Integration guide.

Migration Steps

1. Remove Turnstile dependencies

   • Delete the Turnstile script and widget code
   • Remove related backend verification logic

2. Install ALTCHA

   • Deploy ALTCHA Sentinel or use an existing instance
   • Follow the Widget Integration guide
   • Add <altcha-widget> to your forms

3. Add server-side verification

   • Validate ALTCHA responses using ALTCHA’s verification method

Benefits of Migration

• Complete control with a self-hosted solution
• Fully transparent and auditable code
• No third-party data sharing or tracking
• Minimal latency and performance-friendly

Troubleshooting

See the Troubleshooting guide for help with common issues.

Further Reading

• ALTCHA Sentinel
• Widget Integration
• Server Integration
• Libraries and Plugins