Skip to main content

taCAPTCHA

Privacy-friendly CAPTCHA that protects user privacy while preventing bot abuse.

⚡ Quickstart Guide (< 5 min)​

1. Include taCAPTCHA Assets​

First, include the taCAPTCHA CSS and JavaScript in your HTML:

<!-- Include taCAPTCHA CSS and JavaScript -->
<link rel="stylesheet" href="https://captcha.trustedaccounts.org/static/trusted-accounts-captcha.css">
<script async defer src="https://captcha.trustedaccounts.org/static/trusted-accounts-captcha.js" type="module"></script>

2. Add taCAPTCHA to Your Form​

taCAPTCHA supports multiple challenge types. Choose the one that best fits your security needs.

Frictionless Captcha (Default)​

Frictionless Captcha presents users with a simple arithmetic problem. This is the default challenge type and is ideal for most use cases. No configuration needed - it uses the default endpoints automatically.

<form method="post">
  <!-- Frictionless Captcha (default) -->
  <ta-captcha name="custom-captcha-name"></ta-captcha>
</form>

Code Captcha​

Code Captcha displays a visual text code that users must enter. This provides enhanced security for high-risk scenarios.

<form method="post">
  <!-- Code Captcha -->
  <ta-captcha 
    name="custom-captcha-name"
    challengeurl="https://captcha-server.trustedaccounts.org/v1/captcha/text"
  ></ta-captcha>
</form>

3. Server-Side Verification​

info

The verification endpoint requires authentication using your secret key. Get your secret key by creating a free account, then retrieve it from your project settings.

What is the CAPTCHA token and why do i have to verify it? The CAPTCHA token is a cryptographically signed payload that proves the user completed the challenge. The widget automatically includes it in the form data when submitted, which is why you receive it in req.body. You must verify it on your server to ensure the token is valid and hasn't been tampered with, preventing bots from bypassing the CAPTCHA.

Here's how to verify the CAPTCHA token on your server with a simple API call:

app.post('/submit', async (req, res) => {
  // Verify the CAPTCHA token by sending it to the verification endpoint
  // Replace 'YOUR_SECRET_KEY' with your actual secret key from the admin panel
  const verifyData = await fetch('https://captcha-server.trustedaccounts.org/v1/verify/captcha', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_SECRET_KEY', // ⚠️ Required: Your secret key from the admin panel
    },
    body: JSON.stringify({
      payload: req.body['custom-captcha-name'], // Get the CAPTCHA token from the form data
    }),
  }).then(res => res.json());
  
  if (verifyData.verified) {
    // CAPTCHA is valid, process the form
  } else {
    // CAPTCHA verification failed
  }
});

Configuration​

You can customize the widget behavior using the following attributes:

Basic Configuration​

  • name (string): The name attribute for the form field. Default: "altcha".
  • challengeurl (string): URL endpoint for fetching challenges. Required for custom challenge types.
  • auto (string): Auto-verification mode. Options: "off", "onfocus", "onload", "onsubmit". Default: "off".

Display Options​

  • language (string): Set the widget language (e.g., "en", "de", "fr"). Auto-detected from <html lang> by default.
  • hidelogo (boolean): Hide the ALTCHA logo. Default: false.

Advanced Options​

  • debug (boolean): Enable debug mode for development. Default: false.
  • test (boolean | number): Enable test mode (bypasses actual verification). Default: false.
  • delay (number): Delay in milliseconds before starting verification. Default: 0.
  • disableautofocus (boolean): Disable automatic focus on the widget. Default: false.
  • workers (number): Number of Web Workers for computation. Default: Based on hardware concurrency.

Example​

<ta-captcha
  name="my-captcha"
  challengeurl="https://captcha-server.trustedaccounts.org/v1/captcha/text"
  language="en"
  auto="onload"
  hidefooter="false"
  debug="false"
></ta-captcha>

For a complete list of configuration options, refer to the ALTCHA npm package documentation.

Internationalization (i18n)​

taCAPTCHA supports 50+ languages. The external build includes English by default. To use other languages, you need to load the language-specific i18n file.

Loading Language Files​

To use a language other than English, include the corresponding i18n script before your taCAPTCHA widget:

<!-- Include taCAPTCHA CSS and JavaScript -->
<link rel="stylesheet" href="https://captcha.trustedaccounts.org/static/trusted-accounts-captcha.css">
<script async defer src="https://captcha.trustedaccounts.org/static/trusted-accounts-captcha.js" type="module"></script>

<!-- Load German language file (example) -->
<script async defer src="https://captcha.trustedaccounts.org/i18n/de.js" type="module"></script>

Using the Language Attribute​

After loading the language file, set the language attribute on your <ta-captcha> element:

<form method="post">
  <ta-captcha 
    name="custom-captcha-name"
    language="de"
  ></ta-captcha>
</form>

Available Languages​

Language files are available for all languages supported by ALTCHA. Common examples include:

  • de.js - German
  • fr.js - French
  • es.js - Spanish
  • it.js - Italian
  • And 50+ more languages

The language code should match the filename (e.g., de.js uses language="de").

Language Detection​

If you don't specify a language attribute, taCAPTCHA will automatically detect the language from:

  • The <html lang="..."> attribute
  • The user's browser settings (navigator.languages)

Supported Browsers​

taCAPTCHA works on modern browsers with Web Crypto API support (specifically crypto.subtle - caniuse.com).

Supported:

  • Chrome 67+ (desktop & Android)
  • Edge 79+
  • Firefox 63+ (desktop & Android)
  • Safari 11+ (macOS & iOS)
  • Any browser supporting Web Components + Web Crypto

Not Supported:

  • Internet Explorer 11 (or older)

🎯 Use Cases​

  • Form Protection: Prevent spam submissions
  • Registration Security: Block automated account creation
  • Comment Systems: Filter out bot comments
  • E-commerce: Protect checkout processes
  • API Endpoints: Secure public APIs

🔗 Related Tools​

Ready to implement? Get your publishable key from the Developer Console and start protecting your forms!

Credits​

taCAPTCHA is built on ALTCHA, an open-source privacy-friendly CAPTCHA solution. We extend ALTCHA with our own features and tools, including integration with the Trusted Accounts suite, custom challenges, and enhanced server-side capabilities. We extend our gratitude to the ALTCHA project and its contributors for their excellent work in creating a privacy-first approach to bot protection.