> ## 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.
# Human Presence
> Understanding what human presence means in BotShield
# Human Presence
Human presence is the core concept that BotShield verifies. Understanding what it means and how it differs from other verification methods is key to evaluating BotShield for your platform.
## What is Human Presence?
Human presence is the **verification that a human is physically present** at the moment an action is taken. It is not about:
* Behavior patterns
* Device fingerprints
* Session history
* User accounts or identity
It is about confirming that **a real human** is performing the action **right now**, using hardware-backed biometric authentication on their device.
## Why Human Presence Matters
Automated systems can replicate user behavior patterns, solve CAPTCHAs, and pass behavioral analysis
Actual human presence verified through device biometrics (Face ID / Touch ID) cannot be faked by bots
## How BotShield Verifies Presence
BotShield uses the device's built-in biometric and authentication hardware:
1. **Hardware-backed authentication** -- Face ID, Touch ID, or device passcode via the Secure Enclave
2. **Real-time interaction** -- The authentication happens at the moment of the action
3. **Cryptographic attestation** -- The result is a signed Human Presence Signal (HPS) token
This is fundamentally different from:
* **CAPTCHA** -- Solves puzzles (can be automated by CAPTCHA-solving services)
* **2FA** -- Requires user account and device ownership verification
* **Behavior Analysis** -- Tracks patterns over time (can be mimicked)
* **Device Fingerprinting** -- Identifies devices, not humans
## Properties of Presence
### Presence is Transient
Presence exists only at the moment of action. It is not stored, tracked, or reused.
### Presence is Action-Scoped
Verification is limited to the specific action:
* Checking out -- verify presence for checkout
* Buying tickets -- verify presence for ticket purchase
* Signing up -- verify presence for signup
### Presence is Consumed
Once verified, the HPS is consumed by the action:
* No reuse across actions
* No session persistence
* No cross-platform tracking
### Presence Requires Secure Device State
The user's device must have a system passcode enabled. Without it, BotShield cannot issue a valid attestation. [Learn more about device security requirements](/concepts/device-security).
## Census Result States — What a Partner Sees
Census performs one operation: **anonymous human attestation** — one operation, no modes. No identity ever crosses the partner boundary — Census tells you *that* a human verified, never *who*. At the partner contract, every Census event projects to one of three result states:
| Result state | Meaning |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Human Verified** | A real human completed a fresh, hardware-backed presence check for this action |
| **MultiPass Active** | The user holds an active MultiPass credential — presence was confirmed recently and the freshness window is still open, so they pass through without re-verifying |
| **Human Unavailable** | Verification could not be completed (declined, device not eligible, or the link expired) |
These three states are the partner-facing vocabulary. They are derived inside BotShield from a finer-grained internal decision pair (`verdict` + `reason`) via `deriveCensusResultState` in the engine's verdict grid — partners never see the raw pair.
### Internal Verdict + Reason (engine only)
Internally, a single presence event is binary — the user either passed the biometric check or did not. But the engine needs more nuance than binary to decide *Human Verified* vs *MultiPass Active* vs *Human Unavailable*. It computes a **two-field decision pair**:
| Field | Values | Meaning | Projects to |
| --------- | ---------------------------- | ----------------------------------------------------------------------- | --------------------------------- |
| `verdict` | `pass` | No further verification needed | Human Verified / MultiPass Active |
| `verdict` | `require_presence` | Run the full Face ID flow | (human present, not yet verified) |
| `verdict` | `blocked` | Verification could not complete | Human Unavailable |
| `reason` | `multipass_active` | Pass on credential continuity (passkey + presence consent + valid TTL) | MultiPass Active |
| `reason` | `presence_fresh` | Pass on a fresh Face ID event in the current session window (5 minutes) | Human Verified |
| `reason` | `multipass_stale` | Standard scope, MultiPass freshness lapsed — verify again | — |
| `reason` | `elevated_requires_presence` | Elevated scope demands live proof, even when MultiPass is active | — |
| `reason` | `no_resolution` | Unknown user — establish presence first | — |
Two scope levels drive the verdict: **standard** scopes pass on either MultiPass continuity or fresh Face ID; **elevated** scopes always require live Face ID. Partners configure scope per action — see [Action-Scoped Enforcement](/concepts/action-scoped-enforcement).
Platforms enforce off the result state. **BotShield attests. Platforms enforce.**
## What BotShield Does NOT Return to Partners
**No identity ever crosses the boundary.** Census performs one operation: anonymous human attestation — one operation, no modes (no linked-account or "private" toggle), and partners never receive an email, a BotShield user id, an `auth_mode`, or any identity-bearing token. You learn *that* a human verified, never *who*. You correlate the result to your own system by the `request_id` you generated and the `metadata` you supplied. See [Webhooks](/concepts/webhook-payloads).
BotShield also internally tracks a user-facing **Human Presence tier** (New / Stable / Strong / Durable) on the user's Account tab — but **this tier is never returned to partners**. Per Engine Spec v3.4 §2.6 + §6.4 the visible tier is presence-only ("how human") and intentionally separate from MultiPass durability ("how durable"). The tier informs the user about their own presence trajectory and is not part of any partner integration. Partners see only the anonymous result state.
## Benefits of Presence Verification
No tracking, profiling, or surveillance
5-second verification for returning users
Hardware-backed -- stops bots reliably
Works for any action type via REST API or SDK
Human presence is the first of two attestations BotShield produces. The second — a **Proof of Resolution** — is produced by [BotShield Queue](/queue/overview) when a human confirms a specific action an AI agent proposed on their behalf. Both are anonymous and hardware-backed; presence answers "is a human here?", while a Proof of Resolution answers "did the authorized human confirm this exact action?".
## Related Concepts
* [Webhooks](/concepts/webhook-payloads) -- How anonymous Census results reach your server
* [Trusted Account Signal](/concepts/trusted-account-signal) -- Class A/B classification and how mature linkages strengthen MultiPass durability
* [Signal Durability](/concepts/signal-durability) -- The streak mechanism that drives the MultiPass TTL window
* [Device Security](/concepts/device-security) -- Why device passcode is required
* [Action-Scoped Enforcement](/concepts/action-scoped-enforcement) -- How verification is scoped per action and how scopes resolve to standard vs elevated