Migrating from Open-Source ALTCHA

This guide helps you migrate from the open-source version of ALTCHA to ALTCHA Sentinel, a powerful, self-hosted anti-spam protection system.

Key Differences

Both the open-source version and ALTCHA Sentinel offer the same strong guarantees around privacy and accessibility. They are fully self-hosted, with no reliance on third-party services.

The main difference is in functionality. ALTCHA Sentinel is a ready-to-use solution that includes powerful, built-in features such as:

Adaptive CAPTCHA with code challenges
Text classification
IP reputation and geolocation
Email verification
Built-in rate limiting and more

For a detailed breakdown, see the comparison table.

Implementation Differences

Frontend:

Both versions use the same ALTCHA Widget. The only difference is the challengeurl, which must point to your Sentinel deployment and include your API key:

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

Backend (Node.js example):

With Sentinel, use the verifyServerSignature function instead of the verifySolution function used with the open-source version:

import { verifyServerSignature } from "altcha-lib";

const payload = req.body["altcha"];
const apiKeySecret = "sec_...";

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

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

See the server verification flow diagrams to understand the differences between Sentinel and the open-source approach.

Migration Steps

Deploy ALTCHA Sentinel
- Set up your Sentinel instance
Update the Widget Integration
- Change the challengeurl in the <altcha-widget> to point to your Sentinel instance with your API key
Update Server-Side Verification
- Use verifyServerSignature to validate the payload received from the widget
- If the library is not available in your environment, you can use the POST /v1/verify/signature endpoint to verify the payload.

Why Migrate?

Gain access to advanced features
Improve protection using Adaptive CAPTCHA
Leverage the Classifier API and Similarity API

Troubleshooting

Need help? Check the Troubleshooting guide for common issues and solutions.