Getting started

Installation

This guide installs aiCaptcha on your website — the pages your visitors fill in, and the backend that receives them. No downloads, no build step: the whole installation is one script tag, one div, and one server-side call.

1. Register your site & get your keys

1. Create an account on the aiCaptcha instance you're using (on this one: register here).
2. In the dashboard, open Sites → Add New Site and enter the domain the captcha will run on — e.g. example.com, without https://.
3. Expand the site card and copy the two keys:
   • Site Key (IZAAAAA…) — public, goes into your HTML.
   • Secret Key (dIZAAAAA…) — private, stays on your server.

2. Add the widget to your page

Two lines of HTML. Load the script once per page, and put an empty div wherever the captcha badge should appear — normally inside the form you're protecting:

<!DOCTYPE html>
<html>
<head>
  <!-- 1. Load the widget (use the origin of YOUR aiCaptcha instance) -->
  <script src="https://your-instance.com/api/api.js" async></script>
</head>
<body>
  <!-- 2. Your form, with the captcha div inside it -->
  <form method="POST" action="/submit">
    <input type="email" name="email" placeholder="Email" required>
    <textarea name="message" placeholder="Message" required></textarea>

    <!-- 3. The captcha — as simple as a div -->
    <div data-sitekey="YOUR_SITE_KEY" class="ai-captcha"></div>

    <button type="submit">Submit</button>
  </form>
</body>
</html>

Once installed, the widget handles everything automatically:

• Collects behavioral signals (mouse entropy, keystroke rhythm) while the visitor uses the page.
• Verifies itself when it scrolls into view and shows Success! — no clicking, no puzzles.
• Injects a hidden input, <input type="hidden" name="ai-captcha-response">, holding the token — it travels with your form on submit, like any other field.
• Blocks submission until verification finishes, and retries automatically if it fails.

If you use React, Vue or WordPress — or want the aicaptcha:verified event and other options — see Client-side.

3. Verify the token on your server

The token in the form proves nothing on its own — a client can send any string. Before accepting a submission, your backend asks the aiCaptcha API to check it, using the secret key. It's one HTTP call:

GET https://your-instance.com/api/verify-token?secret=YOUR_SECRET&response=TOKEN

A minimal example in plain PHP:

<?php
$secret = getenv('AICAPTCHA_SECRET');              // dIZAAAAA...
$token  = $_POST['ai-captcha-response'] ?? '';     // sent by the widget

$result = json_decode(file_get_contents(
    'https://your-instance.com/api/verify-token?' . http_build_query([
        'secret'   => $secret,
        'response' => $token,
    ])
), true);

if ($result['success'] ?? false) {
    // Human verified — process the submission
    echo "Form submitted successfully!";
} else {
    http_response_code(400);
    exit('CAPTCHA verification failed. Please try again.');
}

The response also carries the AI verdict, so you can enforce your own policy:

{
  "success": true,
  "score": 0.87,        // AI confidence 0..1
  "risk_level": "low"   // low | medium | high
}

Ready-made examples for Node/Express, Next.js, Python and cURL live in Server-side.

4. Test the integration

• Open your page and interact with it briefly — the captcha box should show Success! within a couple of seconds.
• Submit the form — your server should accept it.
• Open Verifications in the aiCaptcha dashboard: your request appears with its AI score, risk level and the reasons behind the verdict.
• Negative test: submit the form with the hidden input removed (or an empty token) — your backend must reject it.