Skip to main content
ALTCHA®

Quick Start

This guide takes you from zero to a fully protected form in a few minutes. You'll create an account, add the ALTCHA widget to your frontend, and verify submissions on your server.

Before you begin

You'll need:

  • A website or application served over HTTPS (the widget requires a secure context)
  • Access to your frontend code and your server-side form handler

Step 1 — Create your account and add a site

  1. Sign up at cloud.altcha.org and complete the registration process.
  2. Navigate to Sites and activate the Cloud plan of your choice — every plan includes a free 30-day trial.
  3. Add your site by entering the URL of the website you want to protect.
  4. Open the site's Integrate tab to find your unique credentials:
    • Challenge URL — used by the widget on your frontend
    • API Key Secret (sec_...) — used by your server to verify submissions

Step 2 — Add the widget to your frontend

Install the widget via npm (recommended):

npm install altcha
import "altcha";

Or load it from the CDN by adding this to your page's <head>:

<script async defer src="https://cdn.jsdelivr.net/gh/altcha-org/altcha/dist/main/altcha.min.js" type="module"></script>

Then place the <altcha-widget> element inside the form you want to protect, configured with your site's Challenge URL from the Integrate tab:

<form method="POST" action="/submit">
  <!-- your form fields -->

  <altcha-widget
    challenge="https://eu.altcha.org/v1/challenge?apiKey=key_..."
  ></altcha-widget>

  <button type="submit">Send</button>
</form>

That's it for the frontend. The widget renders as a lightweight, accessible verification element and automatically adds a hidden field named altcha containing the verification payload to your form submission.

Using a frontend framework? Starter examples are available for React, Vue, Svelte, Angular, and more.

Step 3 — Verify submissions on your server

Every submission must be verified server-side — the widget alone does not protect you. In your form handler, extract the altcha field from the submitted form data and send it to the Cloud verification endpoint together with your API Key Secret. The response includes a verified: boolean telling you whether the submission is legitimate.

Official server libraries are available for several languages:

import { verifyServer } from 'altcha-lib';

const result = await verifyServer({
  payload: '{{ALTCHA}}',  // raw base64 string
  url: 'https://eu.altcha.org/v1/verify/signature',
  secret: 'sec_...',
});

if (result.verified) {
  // ...
}
use AltchaOrg\Altcha\Sentinel;
use AltchaOrg\Altcha\VerifyServerOptions;

$result = Sentinel::verify(new VerifyServerOptions(
  payload: $_POST['altcha'], // raw base64 string
  url: 'https://eu.altcha.org/v1/verify/signature',
  secret: 'sec_...',
));

if ($result->verified) {
  // ...
}
from altcha import verify_server

result = verify_server(
  payload="{{ALTCHA}}", // raw base64 string
  url="https://eu.altcha.org/v1/verify/signature",
  secret="sec_..."
)

if result.verified:
  ...
import altcha "github.com/altcha-org/altcha-lib-go/v2"

result, err := altcha.VerifyServer(ctx, altcha.VerifyServerOptions{
  URL:          "https://eu.altcha.org/v1/verify/signature",
  Payload:      "{{ALTCHA}}",
  Secret:       "sec_...",
})
if err != nil {
  // transport failure: network error, unexpected HTTP status, or ctx cancellation
}
if result.Verified {
  // valid
}
POST https://eu.altcha.org/v1/verify/signature
Content-Type: application/json

{
  "payload": "<altcha form field value>",
  "secret": "sec_..."
}

For the full description of the verification response, see the API reference.

Step 4 — Test your integration

  1. Load your page and confirm the widget renders inside the form.
  2. Submit the form without completing verification — your server should reject it.
  3. Complete verification and submit — the submission should succeed.
  4. Open the Cloud dashboard to see the verification appear in your analytics and logs.

Using WordPress?

If your site runs on WordPress, skip the manual integration and use the ALTCHA WordPress Plugin. Enable Cloud protection under Advanced Settings → Mode, select ALTCHA Sentinel or Cloud, and enter your Challenge URL and API Key Secret.

Troubleshooting

  • The widget doesn't render — make sure your page is served over HTTPS; the widget requires a secure context and will not work on plain HTTP.
  • Forms can't be submitted without JavaScript — the widget requires JavaScript. Visitors with JavaScript disabled will not be able to submit protected forms.
  • Verification always fails — check that your server sends the raw base64 altcha field value unchanged, and that you're using the API Key Secret (sec_...), not the public API key.

For more help, see the troubleshooting guide.

Next steps

Start typing to search...

↑ ↓ Navigate ↵ Select