Skip to content

Bot Protection

Keeps bots off your forms, logins and hosted sites.

Open Bot Protection
Checked against the dashboard on November 18, 2026

Bot Protection has two sides in code. On your page, a small script draws the check and puts a token in your form when a visitor passes. On your server, one request confirms that token with the setup's secret key. Neither needs an account API key: a setup's own site key (public) and secret key (private) are what scope them.

The setups themselves, their plans and their numbers are managed in the dashboard.

On your page

Copy the embed code from the setup; it already holds the setup's site key. This is its shape for each way the check shows.

<script src="https://xuda.ai/dist/runtime/js/captcha-loader.js" async data-sitekey="YOUR_SITE_KEY"></script>
<div class="xuda-captcha" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://xuda.ai/dist/runtime/js/captcha-loader.js" async data-sitekey="YOUR_SITE_KEY"></script>
<div class="xuda-captcha" data-sitekey="YOUR_SITE_KEY" data-mode="invisible"></div>
<script src="https://xuda.ai/dist/runtime/js/captcha-loader.js" data-sitekey="YOUR_SITE_KEY" data-mode="fullpage"></script>
  • Checkbox and Invisible: put the div inside the form you want to protect. On a pass the script fills a hidden field named xuda-captcha-response in that form, so the token is posted with it.
  • Invisible shows nothing. A form sent without a fresh token is held, the check runs, and the form is sent again.
  • Full page is the script alone, in the page's head. The page is covered until the visitor passes, and that tab is not asked again until its pass runs out.
  • A setup whose look is Light or Dark adds data-theme="light" or data-theme="dark".

The check only runs on the setup's allowed domains.

Callbacks

Name a global function on the div (or on the script, for Full page) to be told what happened:

window.xudaCaptcha.execute(element) returns a promise of a fresh token, for a form you send from your own code.

On your server

Post the token and the setup's secret key to captcha_siteverify. Accept the form only when the answer says success. Keep the secret key in your server's own configuration, never in a page.

curl -s https://xuda.ai/cpi/captcha_siteverify \
  -H 'content-type: application/json' \
  -d '{"secret":"YOUR_SECRET_KEY","response":"TOKEN_FROM_THE_FORM"}'
const res = await fetch('https://xuda.ai/cpi/captcha_siteverify', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ secret: 'YOUR_SECRET_KEY', response: token }),
});
const { data } = await res.json();
if (!data.success) throw new Error('The check did not pass');
import requests

res = requests.post(
    'https://xuda.ai/cpi/captcha_siteverify',
    json={'secret': 'YOUR_SECRET_KEY', 'response': token},
)
passed = res.json()['data']['success']

A pass answers:

json
{
  "code": 1,
  "data": {
    "success": true,
    "score": 0.9,
    "level_reached": 0,
    "hostname": "example.com",
    "challenge_ts": 1762950000000,
    "error-codes": []
  }
}
A token is good once, for two minutes

A token is accepted a single time and lives two minutes. Confirm it when the form arrives, not later, and never confirm the same token twice.

When it does not pass

success is false and error-codes says why:

The answer has the same shape as the ones reCAPTCHA and Turnstile give, so server code written for those usually needs only its address and its secret changed.

Plan limits

A check is counted when a visitor's first step reaches a decision. The plan's monthly limit reads the checks on your own sites and forms; anything hosted with Xuda is not counted. Past a limit the AI step is skipped until next month and every check keeps running, so no form breaks. See Plans and billing.

How is this guide?

Last updated on November 12, 2026