BotShield

API Reference

Three ways to integrate. One secure decision.

Use the widget, verify server-side, or use the raw API. No single mouse or device signal is trusted on its own.

<script src="https://bo-tshield.vercel.app/bot-shield.js" data-api-key="bs_live_your_key" data-mode="modal"></script>

<form data-botshield action="/signup" method="post">
  <!-- SDK injects bot_shield_token after silent scoring. -->
</form>

<script>
  // Optional refresh before a sensitive action.
  window.BotShield.refresh();
</script>

Add the exact origin, including https://, to the project allowlist. If the list is empty, all origins are accepted; use an allowlist for production.

Endpoint reference

POST/api/challenge

Score telemetry and issue a short-lived signed token. Issuance is not approval.

apiKeymouseDatatypingDatafingerprintdeviceDatanetworkData
POST/api/verify

Verify server-to-server, apply the project threshold, and consume the token once. Returns { status: &quot;human&quot; | &quot;blocked&quot;, score }.

secretKeytoken
GET/api/stats/realtime

Read public aggregate network metrics and current plan pricing.

Production guidelines

  • Never treat token presence or a client-side score as approval.
  • Keep the secret key server-only and deny every response except status: "human".
  • Use origin allowlists, HTTPS, rate limits, short token TTLs, and one-time token consumption.
  • Start in shadow mode, monitor false positives, then tune strict, balanced, or loose sensitivity.