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) {
  // result.data.claims.signal_strength is the V1.2 tier:
  //   'newborn' | 'growing' | 'strong' | 'trusted'
  const tier = result.data.claims.signal_strength;
  // Apply your platform's policy based on the tier
}

The Primary Output: Signal Strength

Every verification returns a signal_strength claim — a composite tier that reflects how confidently BotShield attests to this human on this device:

Tier	API value	Typical use
New	`newborn`	First-time user — allow with enhanced monitoring
Stable	`growing`	Consistent presence — acceptable for most actions
Strong	`strong`	Long-standing verified user — most platforms allow
Trusted	`trusted`	Highest confidence — pre-cleared for high-value actions

Platforms use the tier to calibrate their own enforcement. BotShield has no opinion on which actions require which tier — that is your policy decision. See Signal Strength for the full guide.

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 claims including signal_strength.

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
`409`	Duplicate pending verification — use `revokeVerification()` first
`500`	Internal server error

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

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

Overview

SDK Operations

Signal Pixel

Verification

API Reference

API Reference

Install

The Primary Output: Signal Strength

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

Overview

SDK Operations

Signal Pixel

Verification

​API Reference

​Install

​The Primary Output: Signal Strength

​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: Signal Strength

Authentication

SDK Methods

Core Verification

Signal Pixel

Session Management

Typical Flow

Error Handling

Next Steps