API Reference

BotShield provides two SDKs for integrating human presence verification:

Frontend SDK — Drop-in web component for your pages (cdn.botshield.ai/sdk.js)
Backend SDK — TypeScript/Node.js library for server-side validation (botshield-sdk on npm)

Get your API keys from the Partner Dashboard → Settings → API & Credentials.

Install

Frontend (CDN)
Backend (npm)

<script src="https://cdn.botshield.ai/sdk.js"></script>

Then render the widget:

const widget = BotShield.render('#container', {
  siteKey: 'pk_live_YOUR_SITE_KEY',
  signals: true,
  onSuccess: ({ token, signal_token }) => {
    // Send to your backend for validation
    fetch('/api/verify', {
      method: 'POST',
      body: JSON.stringify({ token, signal_token }),
    });
  },
});

Or use the HTML element directly:

<botshield-verify
  site-key="pk_live_YOUR_SITE_KEY"
  signals="true"
  onsuccess="handleVerified"
></botshield-verify>

npm install botshield-sdk

import BotShield from 'botshield-sdk';

const client = new BotShield({
  apiKey: process.env.BOTSHIELD_API_KEY, // bs_prod_... or bs_test_...
});

// Validate a verification token
const result = await client.sdk.verifyToken({
  token: req.body.botshield_token,
});

if (result.data.valid) {
  // claims carry: request_id, botshield_user_id, organization_id,
  // partner_user_id, auth_mode, user_email, timing fields. Combine
  // with the verdict + reason from /signal/check or /signal/evaluate
  // to drive your enforcement policy.
}

The Primary Output: Verdict + Reason

The verification flow returns a 2-field decision pair that drives partner enforcement. Both fields are surfaced via /signal/check, /signal/evaluate, and the embed component’s botshield:multipass-status event.

Field	Values	Meaning
`verdict`	`pass`	No further verification needed — proceed with the gated action
`verdict`	`require_presence`	Run the full Face ID / passkey flow
`reason`	`multipass_active`	Pass on credential continuity (passkey + presence consent + valid TTL)
`reason`	`presence_fresh`	Pass on a fresh Face ID event (within the 5-minute lease window)
`reason`	`multipass_stale`	Standard scope, MultiPass freshness lapsed — verify again
`reason`	`elevated_requires_presence`	Elevated scope always demands live proof, even if MultiPass is active
`reason`	`no_resolution`	User isn’t identified — establish identity first

Partners branch on the pair. BotShield has no opinion on which actions require which scope — that is your policy decision. See Human Presence for the full reason enum and the standard/elevated scope canon.

Authentication

All backend SDK calls use your API key in the Authorization header:

Authorization: Bearer bs_prod_your_key_here

Key Type	Prefix	Purpose
Production	`bs_prod_`	Live verification with real users
Test	`bs_test_`	Development and testing

SDK Methods

Core Verification

Create Session

Get an anchor grant token to start creating verification requests.

Create Verification Link

Generate a verification request with deep link, web URL, and QR code.

Verify Token

Validate a verification receipt JWT. Returns the decoded claims.

Check Status

Poll verification status. Returns signed token when complete.

Signal Pixel

Store Signal

Store a Signal Pixel bot score server-side. Returns a tamper-proof signal token.

Validate Signal

Validate a signal token to get the real server-side bot score. One-time use.

Partner Config

Get enabled integrations (Turnstile, etc.) for a site key.

Session Management

Revoke Verification

Cancel a pending verification. Use when create-verification-link returns 409.

Revoke Session

Invalidate an anchor grant token.

Typical Flow

Error Handling

Code	Meaning
`200`	Success
`400`	Invalid or missing parameters
`401`	Invalid or expired token
`403`	Forbidden — includes rate-limit blocks (check `errors[0].code === 'RATE_LIMITED'`, see Rate Limits)
`409`	Duplicate pending verification — use `revokeVerification()` first
`500`	Internal server error

{
  "error": {
    "message": "Description of what went wrong",
    "statusCode": 400
  }
}

For rate-limit specifics — per-key-type limits, the _rateLimit response envelope, and block behavior — see the Rate Limits page.

Next Steps

Web Component Reference — Frontend SDK details, BotShield.render() API
Signal Pixel — Passive bot scoring details
Quick Start — Step-by-step integration walkthrough
npm package — Backend SDK on npm

​API Reference

​Install

​The Primary Output: Verdict + Reason

​Authentication

​SDK Methods

​Core Verification

Create Session

Create Verification Link

Verify Token

Check Status

​Signal Pixel

Store Signal

Validate Signal

Partner Config

​Session Management

Revoke Verification

Revoke Session

​Typical Flow

​Error Handling

​Next Steps

API Reference

Install

The Primary Output: Verdict + Reason

Authentication

SDK Methods

Core Verification

Signal Pixel

Session Management

Typical Flow

Error Handling

Next Steps