# 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](https://cloud.altcha.org) and complete the registration process. 2. Navigate to **Sites** and activate the [Cloud plan](/pricing/) 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 **Keep your secret safe.** The Challenge URL is public and safe to embed in your HTML. The API Key Secret must only be used server-side — never expose it in frontend code. ## Step 2 — Add the widget to your frontend Install the widget via npm (recommended): ```bash npm install altcha ``` ```js import "altcha"; ``` Or load it from the CDN by adding this to your page's ``: ```html ``` Then place the `` element inside the form you want to protect, configured with your site's **Challenge URL** from the Integrate tab: ```html
``` 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](https://stackblitz.com/~/github.com/altcha-org/altcha-starter-react-ts), [Vue](https://stackblitz.com/~/github.com/altcha-org/altcha-starter-vue-ts), [Svelte](https://stackblitz.com/~/github.com/altcha-org/altcha-starter-svelte-ts), [Angular](https://stackblitz.com/~/github.com/altcha-org/altcha-starter-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](/docs/integration/server/) are available for several languages: ### Node.js ```js 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) { // ... } ``` ### PHP ```php 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) { // ... } ``` ### Python ```python 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: ... ``` ### Go ```go 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 } ``` ### HTTP ```txt POST https://eu.altcha.org/v1/verify/signature Content-Type: application/json { "payload": "", "secret": "sec_..." } ``` For the full description of the verification response, see the [API reference](/sentinel-api-docs-v1.html#tag/verify/post/v1/verify/signature). > **Tip:** > > The payload can also be verified cryptographically without an HTTP request, but then you are responsible for preventing [replay attacks](/docs/integration/security-recommendations/) yourself. The remote verification endpoint handles this for you and is the recommended approach. ## 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](/docs/wordpress/). 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](/docs/integration/troubleshooting/). ## Next steps - **[Widget customization](/docs/integration/widget/#themes-and-customization)** — themes, display modes, and branding - **[Internationalization](/docs/integration/widget/#internationalization-i18n)** — 50+ languages supported - **[Pricing](/pricing/)** — compare plans and capacity - **[Introduction](/docs/cloud/)** — learn more about how ALTCHA Cloud works - **[Settings](/docs/cloud/settings/)** — configure your ALTCHA Cloud sites