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.

Storefront Gate

DNS-level protection. No code changes.

​
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
    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;

  const result = await fetch('https://api.botshield.ai/v1/verify', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer sk_live_YOUR_SECRET_KEY',
    },
    body: JSON.stringify({ token: botshield_token }),
  });

  const data = await result.json();

  if (data.valid) {
    // Proceed with checkout
    res.json({ success: true });
  } else {
    res.status(403).json({ error: 'Verification failed' });
  }
});
The Client SDK also supports an iframe mode for passive bot detection without user interaction. See the iframe 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 https://api.botshield.ai/operations/verification/status?request_id=req_xyz789...
Full reference: Server SDK docs | API Reference

​
Option C: Storefront Gate

DNS-level protection for your entire storefront. No code changes. Works on any Shopify plan.

​
1. Add a CNAME Record

Point your storefront domain to BotShield: 
shop.mystore.com  CNAME  gateway.botshield.ai

​
2. Set as Primary Domain

In Shopify (or your platform), set the gated domain as your primary storefront domain.

​
3. Enable Protection

Toggle protection ON in the BotShield Partner Dashboard under Storefront Gate.

​
How It Works

  • Unverified visitors are redirected to a BotShield challenge page
  • On successful verification, a botshield_session cookie is set
  • Subsequent requests pass through to your origin
  • Session TTL: 30-60 minutes (standard) or 3-10 minutes (drop mode)
Full reference: Storefront Gate docs

​
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