Documentation

Read once, integrate forever.

The entire integration surface fits on this page. Examples below are generated from the domain you are reading this on.

Quickstart

Add one script tag to any page. The widget auto-starts in the branded modal, adds a hidden token to forms marked data-botshield, and points its API calls at BotShield automatically.

<script
  src="/bot-shield.js"
  data-api-key="bs_live_your_key"
  data-mode="modal"
></script>

<form data-botshield action="/signup" method="post">
  <!-- bot_shield_token is added after verification -->
</form>

Server-side verification

On form submission, read the hidden bot_shield_token field and verify it from your backend. Never trust the client's word.

const res = await fetch("/api/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ secretKey, token })
});
const { status } = await res.json(); // "human" | blocked

Widget API

The widget scores visitors silently after ~4 seconds and injects a hidden token into your forms. You can also drive it manually.

const token = window.botShield.getToken();
window.botShield.refresh(); // re-score right now

Sensitivity presets

Each project runs in strict, balanced, or loose mode. Strict is for checkout and auth. Loose is for comment sections with forgiving hearts.

strict   → block at score ≥ 30
balanced → block at score ≥ 50
loose    → block at score ≥ 80

Rate limits

Standard protections ship enabled and are editable live from the admin console.

signups        5 / hour / IP
logins        10 / hour / IP
verify calls 100 / min / key

Error handling

BotShield fails open by design. If our network is unreachable, your users are never locked out. Treat a network error as a pass and log it for review.

try { await verify(); }
catch { allow(); logForReview(); }

Domains & self-host

The widget derives its API origin from its own script URL. Serve it from any domain today or tomorrow and it adapts with zero code changes. The core is open source under MIT.

git clone https://github.com/brave290/bot-shield
cd bot-shield
npm install && npm run dev