Skip to main content

​
Quick Start

Choose the integration that fits your platform:

Client SDK Embed

Drop a script tag on your page. No backend required.

Server SDK

Full control via REST API or TypeScript SDK.

​
Prerequisites

  • A BotShield Partner account (request access)
  • Your site key (pk_live_...) from Settings > Site Keys
  • Your API key (bs_prod_...) from Settings > API & Credentials

​
Option A: Client SDK Embed

The fastest path. Add a single script tag and the <botshield-verify> web component handles everything.

​
1. Add the Script Tag

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

​
2. Add the Widget

Place the widget before your checkout or submit button: 
<botshield-verify
  site-key="pk_live_YOUR_SITE_KEY"
  theme="auto"
  onsuccess="onVerified"
  onfailure="onFailed"
></botshield-verify>

<button id="checkout-btn" disabled>Proceed to Checkout</button>

​
3. Handle the Result

<script>
  function onVerified({ token }) {
    // Human verified -- enable the button
    document.getElementById('checkout-btn').disabled = false;

    // Send token to your server for validation + signal strength
    fetch('/api/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ botshield_token: token }),
    });
  }

  function onFailed({ reason }) {
    console.error('Verification failed:', reason);
  }
</script>

// Your backend endpoint
app.post('/api/verify', async (req, res) => {
  const { botshield_token } = req.body;

  // Call verify-token to validate signature + extract claims
  const result = await fetch('https://api.botshield.ai/operations/sdk/verify-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token: botshield_token }),
  });

  const { data } = await result.json();

  if (!data.valid) {
    return res.status(403).json({ error: 'Verification failed' });
  }

  // The verdict + reason pair drives your enforcement policy.
  // Read them off the verification flow's response (verification/status,
  // /signal/check, or /signal/evaluate — depending on integration shape).
  // Verdict ∈ { 'pass', 'require_presence' }
  // Reason  ∈ { 'multipass_active', 'presence_fresh', 'multipass_stale',
  //             'elevated_requires_presence', 'no_resolution' }
  return res.json({ success: true, claims: data.claims });
});
Your contract is verdict + reason — a 2-field decision pair. pass means proceed; require_presence means run the full Face ID flow. See Human Presence for the full reason enum.
The Client SDK also supports a Signal Pixel mode for passive bot scoring without user interaction. Add signals="true" to the web component. See the Signal Pixel reference for details.
Full reference: Client SDK Embed docs

​
Option B: Server SDK

For platforms that need full backend control over the verification flow.

​
1. Install the SDK

npm install botshield-sdk

​
2. Create a Session

import BotShield from 'botshield-sdk';

const client = new BotShield({
  apiKey: 'bs_prod_YOUR_API_KEY',
});

const session = await client.sdk.createSession({
  partner_user_id: 'your_internal_user_id',
});

const sessionToken = session.data.session_token;

const verification = await client.sdk.createVerificationLink(
  {
    scope: 'checkout.complete',
    sdk_type: 'signal',
    user_email: '[email protected]',
    return_url: 'https://your-site.com/checkout/callback',
    webhook_url: 'https://your-site.com/api/botshield-webhook',
  },
  { headers: { Authorization: `Bearer ${sessionToken}` } }
);

// Send to user:
// verification.data.web_url    -- web browser link
// verification.data.deep_link  -- mobile deep link
// verification.data.qr_code_url -- QR code image

​
4. Receive the Result

Via webhook (recommended): 
{
  "event": "verification.success",
  "request_id": "req_xyz789...",
  "verified_at": "2026-03-16T12:00:00Z",
  "verification_token": "eyJhbGc...",
  "user_email": "[email protected]"
}
Via polling: 
curl -X POST https://api.botshield.ai/operations/verification/status \
  -H "Content-Type: application/json" \
  -d '{"request_id": "req_xyz789..."}'

​
5. Validate the Token

const result = await client.sdk.verifyToken({
  token: verification_token,
});

if (!result.data.valid) {
  return res.status(403).json({ error: 'Invalid token' });
}

// `result.data.claims` carries request_id, botshield_user_id,
// auth_mode, user_email, and timing fields. Combine with the
// verdict + reason from /signal/check or /signal/evaluate to
// drive your enforcement policy. See /concepts/human-presence.
Full reference: Server SDK docs | API Reference

​
What Happens During Verification

Regardless of which option you choose, the user experience is:
  1. BotShield presents a verification prompt
  2. The user authenticates with their device (Face ID, Touch ID, or device passcode)
  3. A signed, one-time-use token is generated
  4. The token is returned to your platform
No personal data is collected. BotShield verifies presence, not identity.

​
Next Steps

SDK Overview

Understand the full architecture and capabilities

Partner Dashboard

Test verification flows in the Playground

How It Works

Learn about Human Presence Signals

Get Access

Request developer credentials