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

> BotShield Census capabilities — anonymous human presence verification

# SDK Features

Census Anonymous Human Attestation performs one operation: anonymous human attestation — one operation, no modes. No identity-bearing data ever crosses the partner boundary.

## Live Human Presence Attestation

Real-time verification that a human is present at the moment of action. Unlike behavior-based detection, BotShield verifies actual human presence using device biometrics (Face ID / Touch ID).

<Warning>
  Bots can mimic behavior, but presence requires a human. Every time.
</Warning>

## Human Presence Signal (HPS)

Each verification produces a short-lived, cryptographically signed HPS:

* Valid only for the specific request/scope
* Expires after use (5-minute window)
* Cannot be reused or replayed
* Delivered via webhook (signed Svix envelope) or polling

The synchronous `verification_token` you can read on a `return_url` or via `verifyToken` is **PII-free** — its claims are only `request_id`, `verified`, `organization_id`, `timestamp`, and `nonce`. There is no email, no auth mode, and no user ID anywhere in the token.

## Anonymous by Default

Census performs one operation: anonymous human attestation — one operation, no modes. There is no linked-account path:

* Partners never receive a user email, name, or BotShield user ID
* Identity lives only in the consumer app's own account system
* Every webhook and token is scoped to a `request_id`, never a person

## Action-Scoped Enforcement

Verification and enforcement are limited to the specific scope being acted on:

* No broad surveillance across your platform
* Verification only when you require it
* No tracking of user behavior outside the action

## MultiPass Continuity

When a returning user has an active passkey, presence consent enabled, and a valid TTL window, **standard** scopes can pass without a fresh biometric — surfaced to you as the **MultiPass Active** result state. Elevated scopes always require live Face ID. Continuity is bound to the device, never to a partner-visible identity.

## Hardware-Backed Security

BotShield requires the user's device to have a system passcode enabled:

* Without a passcode, the OS cannot provide hardware-backed human-gated events
* Attestations are only issued from devices with a secure lock state
* This ensures every HPS is cryptographically and semantically valid
* [Learn more about device security requirements](/concepts/device-security)

## No Persistence of Identity

Each verification is independent of any identity you hold:

* No user profiling
* No cross-action identity storage
* Privacy-first by design

## Usage-Based Pricing

Pay only for verifications you use:

* No monthly minimums
* No hidden fees
* Clear pricing per verification
* See [Deployment Options](/deployment/overview) for tiers

## Technical Capabilities

### REST API + TypeScript SDK

BotShield is integrated server-side via REST API calls, with an optional [TypeScript client library](/sdk/client-libraries) that wraps the same operations:

```bash theme={null}
# Step 1: Create grant window
POST /operations/sdk/create-session
Authorization: Bearer bs_prod_YOUR_API_KEY

# Step 2: Create verification link
POST /operations/sdk/create-verification-link
Authorization: Bearer SESSION_TOKEN
```

### Multiple Delivery Methods

Present verification to users via:

* **Deep link** — Direct app launch on mobile (`botshield://verify?request_id=...`)
* **Web URL** — Browser-based verification flow
* **QR code** — Scannable code for in-store or kiosk scenarios

### Webhook and Polling

Receive verification results via:

* **Webhook** (recommended) — BotShield sends a signed Svix POST to your callback URL. Authenticity is the Svix envelope signature (`svix-id` / `svix-timestamp` / `svix-signature`), verified with your endpoint signing secret (`whsec_...`). The payload is anonymous: `{ type, event_id, request_id, verified_at | failed_at | expired_at, [reason], product, metadata }`.
* **Polling** — Query the verification status endpoint.

### Token Validation

The synchronous `verification_token` is a signed receipt you can validate via `verifyToken`. It carries no identity — only the `request_id`, the `verified` flag, your `organization_id`, a `timestamp`, and a `nonce`.

### Test Mode

Use test API keys (prefix: `bs_test_`) and test site keys (`pk_test_*`) for local development:

* Same endpoints and response format as production
* Lower rate-limit tier than production keys — see [Rate Limits](/api-reference/rate-limits) for the per-bucket caps. Generous for real dev work, but tight enough that running sustained production traffic on a test key is unworkable.

## Security Properties

### What BotShield Does

* Confirms a real human is present on a device at the moment of action
* Produces a cryptographically signed, tamper-proof signal
* Enforces hardware-backed device security (passcode required)
* Ensures each signal is single-use and time-bound

### What BotShield Does Not Do

* Reveal user identity to the partner (presence is not identity)
* Pass any PII across the partner boundary
* Track users across sessions or actions
* Store personal information or biometric data
* Create partner-visible user profiles

## Next Steps

* [Use Cases](/sdk/use-cases) — Real-world applications
* [Quick Start](/quick-start) — Step-by-step integration
* [Client Libraries](/sdk/client-libraries) — Official TypeScript SDK
* [Device Security](/concepts/device-security) — Hardware-backed security requirements
* [Deployment Options](/deployment/overview) — Choose your plan