Installation

Server-side

The client token proves nothing on its own — always verify it server-side with your secret key before accepting a submission. It's one HTTP call:

the shape of it

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

Response

json

{
  "success": true,
  "score": 0.87,       // AI score 0..1 (present when available)
  "risk_level": "low"  // low | medium | high
}

On failure you get { "success": false, "error": "..." } — the possible error values are listed in Error Codes.

Token rules

Tokens are valid for 2 minutes and are bound to the site the widget was registered for. Verify each token as soon as the form arrives — don't store them for later.

PHP

verify.php

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

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

$result = json_decode(file_get_contents($url), true);

if ($result['success'] ?? false) {
    // human — process the form
} else {
    http_response_code(400);
    exit('CAPTCHA verification failed.');
}

Node.js (Express)

routes/submit.js

const express = require("express");
const router = express.Router();

router.post("/submit", async (req, res) => {
  const { "ai-captcha-response": token } = req.body;

  const url = new URL("https://your-instance.com/api/verify-token");
  url.searchParams.set("secret", process.env.AICAPTCHA_SECRET);
  url.searchParams.set("response", token || "");

  const result = await fetch(url).then((r) => r.json());

  if (!result.success) {
    return res.status(400).send("CAPTCHA verification failed.");
  }

  // Optional: enforce your own risk policy
  if (result.risk_level === "high") {
    return res.status(403).send("Request flagged, please try again.");
  }

  res.send("Submitted!");
});

module.exports = router;

Next.js (Route Handler)

app/api/submit/route.ts

export async function POST(req: Request) {
  const form = await req.formData();
  const token = String(form.get("ai-captcha-response") ?? "");

  const url = new URL("https://your-instance.com/api/verify-token");
  url.searchParams.set("secret", process.env.AICAPTCHA_SECRET!);
  url.searchParams.set("response", token);

  const { success, risk_level } = await fetch(url).then((r) => r.json());

  if (!success) {
    return Response.json({ error: "captcha_failed" }, { status: 400 });
  }

  // process the submission...
  return Response.json({ ok: true });
}

Python

views.py

import os, requests

def submit(request):
    token = request.POST.get("ai-captcha-response", "")
    r = requests.get(
        "https://your-instance.com/api/verify-token",
        params={
            "secret": os.environ["AICAPTCHA_SECRET"],
            "response": token,
        },
        timeout=5,
    ).json()

    if not r.get("success"):
        return HttpResponse("CAPTCHA verification failed.", status=400)

    # process the submission...
    return HttpResponse("Submitted!")

cURL

bash

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

# POST also works (form-encoded, reCAPTCHA-style)
curl -X POST https://your-instance.com/api/verify-token \
  -d "secret=YOUR_SECRET" \
  -d "response=TOKEN"

Using the score

success already encodes the default policy (score ≥ 0.7). For finer control, branch on score or risk_level:

if (!result.success)        reject();        // score < 0.7
else if (score < 0.85)      challenge();    // gray zone — add your own fallback
else                        accept();       // clearly human

How the score is produced: AI Scoring Engine. Endpoint details: API Reference.