> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get BotShield human presence verification running on your site in minutes

# Quick Start

Choose the integration that fits your platform:

<CardGroup cols={2}>
  <Card title="Client SDK Embed" icon="code" href="#option-a-client-sdk-embed">
    Drop a script tag on your page. No backend required.
  </Card>

  <Card title="Server SDK" icon="server" href="#option-b-server-sdk">
    Full control via REST API or TypeScript SDK.
  </Card>
</CardGroup>

## Prerequisites

* A BotShield Partner account ([request access](https://botshield.ai/pricing))
* 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

```html theme={null}
<script src="https://cdn.botshield.ai/sdk.js"></script>
```

### 2. Add the Widget

Place the widget before your checkout or submit button:

```html theme={null}
<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

```html theme={null}
<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>
```

### 4. Validate Server-Side (Recommended)

The widget's `onsuccess` token is the **PII-free** `verification_token`. Validate it on your server to confirm the signature before you act on it:

```javascript theme={null}
// 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 || !data.claims.verified) {
    return res.status(403).json({ error: 'Verification failed' });
  }

  // The token is anonymous by construction. Its claims are only:
  //   { request_id, verified, organization_id, timestamp, nonce }
  // There is NO email, user id, device data, or auth_mode in the token.
  // Correlate to your own order/session by the request_id you created.
  return res.json({ success: true, request_id: data.claims.request_id });
});
```

<Tip>
  Census returns one of three **result states** — Human Verified, MultiPass Active, or Human Unavailable. The widget renders these for you; a verified token (`verified: true`) corresponds to a Human Verified or MultiPass Active result. See [Human Presence](/concepts/human-presence) for the full model.
</Tip>

<Tip>
  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](/embed/signal-pixel) for details.
</Tip>

**Full reference:** [Client SDK Embed docs](/embed/overview)

***

## Option B: Server SDK

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

### 1. Install the SDK

```bash theme={null}
npm install botshield-sdk
```

### 2. Create a Session

```typescript theme={null}
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;
```

### 3. Create a Verification Link

```typescript theme={null}
const verification = await client.sdk.createVerificationLink(
  {
    scope: 'checkout.complete',
    sdk_type: 'signal',
    return_url: 'https://your-site.com/checkout/callback',
    metadata: { order_id: 'checkout-12345' }, // your own correlation data
  },
  { 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).** Anonymous by construction — no identity, signed with Svix:

```json theme={null}
{
  "type": "census.human_verified",
  "event_id": "req_xyz789...",
  "request_id": "req_xyz789...",
  "verified_at": "2026-06-16T12:00:00Z",
  "product": "census",
  "metadata": { "order_id": "checkout-12345" }
}
```

**Via polling:**

```bash theme={null}
curl -X POST https://api.botshield.ai/operations/verification/status \
  -H "Content-Type: application/json" \
  -d '{"request_id": "req_xyz789..."}'
```

### 5. Verify the Webhook

The webhook's authenticity is the **Svix signature** over the payload — there's no identity in the body and no token to decode. Verify with the `svix` library and your endpoint's signing secret (from **Console → Settings → Webhooks**), then act on `type` + `request_id`:

```typescript theme={null}
import { Webhook } from "svix";

const wh = new Webhook(process.env.BOTSHIELD_WEBHOOK_SECRET!); // whsec_...
const evt = wh.verify(rawRequestBody, {       // pass the RAW body, not parsed JSON
  "svix-id": req.header("svix-id")!,
  "svix-timestamp": req.header("svix-timestamp")!,
  "svix-signature": req.header("svix-signature")!,
});

if (evt.type === "census.human_verified" || evt.type === "census.multipass_active") {
  await completeCheckout(evt.request_id, evt.metadata); // correlate by your own request_id
}
```

Full walkthrough (idempotency, retries, all event types): **[Webhooks — Payloads & Verification](/concepts/webhook-payloads)**.

**Full reference:** [Server SDK docs](/sdk/client-libraries) | [API Reference](/api-reference/overview)

***

## 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

<CardGroup cols={2}>
  <Card icon="book-open" href="/sdk/overview" title="SDK Overview">
    Understand the full architecture and capabilities
  </Card>

  <Card icon="flask" href="https://console.botshield.ai" title="Partner Dashboard">
    Test verification flows in the Playground
  </Card>

  <Card icon="shield" href="/concepts/human-presence" title="How It Works">
    Learn about Human Presence Signals
  </Card>

  <Card icon="key" href="https://botshield.ai/pricing" title="Get Access">
    Request developer credentials
  </Card>
</CardGroup>