Skip to main content

Migration from Open-Source ALTCHA

This guide helps you migrate from self-hosted / open-source ALTCHA (Web Component or bundled widget + your verify route) to MTCaptcha when you want a managed script + CheckToken API instead of operating your own challenge backend.

Why migrate from open-source ALTCHA​

  • Privacy and GDPR alignment: Reduce bespoke data flows through self-hosted verification endpoints; align with MTCaptcha’s documented privacy model. See Privacy GDPR Compliance.
  • WCAG 2.1 AAA accessibility: Standardize on MTCaptcha’s accessibility posture and published materials. See Accessibility Compliance.
  • Global reliability, including China: Replace self-managed regional routing with MTCaptcha’s delivery, including documented mainland China support. See Works in China.

Migration at a glance​

Open-source ALTCHAMTCaptcha
Client scriptPackaged ALTCHA client (e.g. altcha.min.js from your bundle) or ES module importhttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Widget classTypically <altcha-widget> or framework wrapper you mount.mtcaptcha (<div class="mtcaptcha"></div>)
Token nameImplementation-specific (often a custom field name in your form POST mirroring ALTCHA’s payload)mtcaptcha-verifiedtoken
Backend APIYour server route that validates the ALTCHA payload (self-hosted)GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Server-side verification only

Your MTCaptcha PrivateKey must stay on the server. The browser only receives the public SiteKey via mtcaptchaConfig.

Step 1: Replace client-side widget integration​

<!-- Remove [ALTCHA] — remove your <altcha-widget> / init code and ALTCHA script tags -->

<!-- Add [MTCaptcha] -->
<script>
  var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" };
</script>
<script src="https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js" async defer></script>
<div class="mtcaptcha"></div>
Load order

Initialize mtcaptchaConfig with "sitekey" before loading mtcaptcha.min.js.

Step 2: Replace server-side verification​

Remove calls to your ALTCHA verification handler and call MTCaptcha CheckToken instead:

GET https://service.mtcaptcha.com/mtcv1/api/checktoken?privatekey=YOUR_PRIVATEKEY&token=VERIFIED_TOKEN

Parse mtcaptcha-verifiedtoken from the request body (not your former ALTCHA field name).

Token lifetime and single use

Expect short TTLs and single-use semantics by default. See Validate Token (With Private Key).

Use https://service2.mtcaptcha.com/mtcv1/api/checktoken if you require fixed outbound IP allowlisting.

Troubleshooting​

SymptomWhat to check
Two widgets on screenRemove leftover ALTCHA components before mounting MTCaptcha.
Old field still validatedSearch codebase for prior ALTCHA field names and tests.
Verify route still hitDelete unused ALTCHA routes to avoid false “success” paths.
CSPAllow https://service.mtcaptcha.com (and service2 if used).

Further reading​

Post-Migration Checklist​

  • Removed ALTCHA client bundles, widgets, and server verification code.
  • mtcaptchaConfig with "sitekey": "YOUR_SITEKEY" precedes mtcaptcha.min.js.
  • All forms POST mtcaptcha-verifiedtoken and server uses https://service.mtcaptcha.com/mtcv1/api/checktoken.
  • Monitoring/logging updated (no ALTCHA-specific errors).
  • CSP/network paths validated.