Skip to main content

​
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.
Access to the BotShield API is provisioned through a developer application process. Once approved, you receive an API key (bs_prod_* / bs_test_*) and a public site key (pk_live_* / pk_test_*) for client-side embeds.

​
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

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:
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: For the full internal verdict + reason grid that projects to these states, see Human Presence.

​
API Flow

​
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: Scopes are registered and approved in the Partner Dashboard 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