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

# SDK Overview

> Understanding the BotShield API architecture and integration model

# BotShield SDK Overview

BotShield provides a REST API (and a thin TypeScript wrapper) for integrating anonymous human presence verification into your platform. Integration happens server-to-server, with the user completing a biometric check on their own device. No personally identifiable information ever crosses the BotShield boundary.

<Info>
  Access to the BotShield API is provisioned through a [developer application process](https://botshield.ai/pricing). Once approved, you receive an API key (`bs_prod_*` / `bs_test_*`) and a public site key (`pk_live_*` / `pk_test_*`) for client-side embeds.
</Info>

## Anonymous by Design

Census performs one operation: **anonymous human attestation** — one operation, no modes. No identity-bearing path exists at the partner boundary:

* The partner never sees a user email, name, or BotShield user ID.
* Identity (if any) lives only in the consumer app's own account system — never in a verification payload, webhook, or token.
* Every artifact you receive carries a `request_id` and a verification result. Nothing more.

This is the core privacy property: you learn **that a human was present**, never **who** they are.

## Integration Model

```
Partner Server → BotShield API → Verification Link → User's Device → Biometric Check → Partner Server
```

The integration is entirely server-side on your end. Your server:

1. **Creates a grant window** (session token) using your API key
2. **Creates a verification link** for a specific scope
3. **Presents the link** to the user (deep link, web URL, or QR code)
4. **Receives the result** via webhook or polling

The user:

1. Opens the BotShield app (or is prompted to set it up on first use)
2. Completes a biometric check (Face ID / Touch ID)
3. Is returned to your platform

## Human Presence Signal (HPS)

Each successful verification produces an **HPS** — a short-lived, cryptographically signed attestation that confirms:

* A real human was present on a device
* The verification occurred within the expiry window
* The signal is tamper-proof and single-use

The HPS is delivered to your server via webhook or polling. The synchronous `verification_token` you can receive on the `return_url` (or from `verifyToken`) is **PII-free** — its claims are only:

```json theme={null}
{
  "request_id": "req_...",
  "verified": true,
  "organization_id": "org_...",
  "timestamp": "2026-06-16T12:00:00Z",
  "nonce": "..."
}
```

There is no email, no auth mode, and no BotShield user ID in the token.

## Result States

Census collapses BotShield's internal verdict logic into three partner-facing result states:

| Result State          | Meaning                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Human Verified**    | A fresh Face ID / passkey presence event completed for this request.                                                                   |
| **MultiPass Active**  | The user passed on credential continuity (an active passkey + presence consent within a valid TTL window) — no fresh biometric needed. |
| **Human Unavailable** | Verification could not complete (expired, declined, or the user could not satisfy the check).                                          |

For the full internal verdict + reason grid that projects to these states, see [Human Presence](/concepts/human-presence).

## API Flow

```
POST /operations/sdk/create-session
  → Returns session_token (bss_*), organization info

POST /operations/sdk/create-verification-link
  → Returns deep_link, web_url, qr_code_url, request_id
  → If 409 Conflict: call revoke-verification first, then retry

User completes verification in BotShield app

POST webhook → your server receives a signed envelope (Svix)
  OR
GET /operations/verification/status?request_id=...
  → Returns status + verification_token

Optional cleanup:
POST /operations/sdk/logout
  → Revokes an unused session token

POST /operations/sdk/revoke-verification
  → Cancels a stuck pending verification for a scope + user
```

### What a Verification Guarantees

**Guaranteed:**

* A real human was present on a device at verification time
* Verification occurred within the expiry window
* The signal is cryptographically signed and tamper-proof
* The signal cannot be replayed (one-time use)

**Not guaranteed:**

* User identity (presence is not identity — and BotShield never reveals it)
* Device ownership
* Account state
* Future presence (the signal expires quickly)

## MultiPass

MultiPass is BotShield's continuity layer. When a user has an active passkey on their device, presence consent enabled, and a valid TTL window, a **standard** scope can pass without a fresh biometric — the user sees no friction, and you get a **MultiPass Active** result. **Elevated** scopes always require a live Face ID, even when MultiPass is active.

MultiPass continuity is anonymous: it is bound to the device and routing handle, never to an identity the partner can see.

## Scopes

A scope defines the specific action being verified. Each scope maps to one action on your platform, following the format `category.action`:

| Scope                 | Description                  |
| --------------------- | ---------------------------- |
| `checkout.complete`   | Complete a purchase          |
| `payment.authorize`   | Authorize a payment          |
| `listing.create`      | Create a marketplace listing |
| `bid.place`           | Place a bid on an item       |
| `withdrawal.initiate` | Initiate a fund withdrawal   |

Scopes are registered and approved in the [Partner Dashboard](https://console.botshield.ai) before use. Each scope resolves to one of two canonical impact levels — `standard` (MultiPass continuity *or* a fresh Face ID is sufficient) or `elevated` (live Face ID always required). BotShield has no opinion on which of your actions need which scope; that is your policy decision.

## Next Steps

* [Quick Start](/quick-start) — Step-by-step integration guide
* [SDK Features](/sdk/features) — Detailed capabilities
* [Use Cases](/sdk/use-cases) — Real-world applications
* [Client Libraries](/sdk/client-libraries) — Official TypeScript SDK
* [API Reference](/api-reference/overview) — Endpoint documentation