Migrating from reCAPTCHA

This guide helps you migrate from Google’s reCAPTCHA to ALTCHA Sentinel, a privacy-friendly alternative that doesn’t track users or require invasive challenges.

Key Differences

Feature	reCAPTCHA	ALTCHA
Challenge Type	Often intrusive puzzles	Frictionless or code challenge
Implementation	Requires Google services	Self-hosted
Accessibility	Can present barriers to users	WCAG compliant, screen-reader friendly
Privacy	Tracks users across sites	No tracking, privacy-focused
Compliance	Concerns	GDPR, CCPA, HIPAA, CPPA, LGPD, DPDPA, PIPL compliant
Verification	Server-to-Google API call	Fast, local cryptographic verification
Limit	< 10,000 / month	Unlimited

Implementation Comparison

reCAPTCHA (Previous Implementation)

Frontend:

<script src="https://www.google.com/recaptcha/api.js"></script>
<div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>

Backend (Node.js example):

const response = req.body["g-recaptcha-response"];

const secret = "YOUR_SECRET_KEY";

const resp = await fetch(
  `https://www.google.com/recaptcha/api/siteverify?secret=${secret}&response=${response}`,
  {
    method: "POST",
  }
);

const verification = await resp.json();

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

ALTCHA Sentinel (New Implementation)

Frontend:

Import the altcha package in your app or website:

import "altcha";

Include the <altcha-widget> into 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.

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

Remove reCAPTCHA dependencies
- Delete Google reCAPTCHA script tags
- Remove any server-side verification code
Install ALTCHA
- Deploy your ALTCHA Sentinel instance
- Follow the Widget Integration guide
- Add the <altcha-widget> to your forms
Implement server-side verification
- Use the verification helper to validate challenges on form submission

Benefits of Migration

Improved page load performance
Accessible and frictionless protection
No tracking or user profiling
Reduced compliance overhead

Troubleshooting

For common integration issues, refer to the Troubleshooting guide.