> ## 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.
# BotShield Queue (Q)
> Agentic, human-in-the-loop authorization — a Trusted Agent proposes an action, the user confirms with a biometric, and BotShield issues a Proof of Resolution.
# BotShield Queue (Q)
BotShield Queue — **Q** — is the agentic product. Where [Census](/concepts/human-presence) gates an action a human takes *on your own surface*, Q gates an action an **agent proposes on the user's behalf** and routes the human-in-the-loop confirmation through the user's own device.
The shape is simple:
1. A **Trusted Agent** (Claude, ChatGPT, or any agent you register with BotShield) proposes an action — "the user wants to book this flight; confirm it with them."
2. BotShield delivers a **BotShield Q push notification** to the user's BotShield app and queues a **Q card** describing the action.
3. The user reviews the card and taps **Confirm** or **Deny**, backed by a hardware biometric (Face ID / Touch ID via the Secure Enclave).
4. BotShield issues a **Proof of Resolution** — a cryptographically signed attestation of the user's verdict, bound to that exact action — and delivers it back to the agent.
**BotShield attests. The agent enforces.** BotShield produces a signed Proof of Resolution; the agent decides what that verdict permits. BotShield never makes an authorization determination on the agent's behalf.
## Why Q exists
Agents can act for a user, but a chat or text surface is the wrong place for a biometric. The agent's surface can't produce a hardware-backed proof a partner can trust, and replaying a "yes" from a chat log proves nothing.
Q decouples the confirmation from the agent. The biometric ceremony happens in **BotShield's own app**, on the user's own device, which makes the resulting attestation:
The proof is produced by BotShield, not the agent. Any agent — or your backend — verifies it the same way.
The verdict is signed only after a real Face ID / Touch ID ceremony fires the device's Secure Enclave passkey.
Each Proof of Resolution is bound to one `request_id` and one action. A proof for one action cannot authorize a different one — replay is structurally impossible.
The proof is an ES256 JWT. Verify it locally with BotShield's published public key — no round-trip required.
## How it maps to your integration
| Role | Who | What they hold |
| --------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trusted Agent** | The AI agent acting for the user | An agent API key (`bs_agent_…`). Calls the [Q API](/queue/api-reference) to propose actions and poll for the result. |
| **User** | The person the agent acts for | The BotShield app. Reviews Q cards, confirms with biometric. A registered BotShield user; a linked **Trusted Account** is recommended but not required. |
| **Your backend** (optional) | Your platform | Receives [webhook events](/queue/proof-of-resolution) and verifies the Proof of Resolution to release the action. |
## Asynchronous by design
Q is asynchronous. The agent proposes an action and the user may respond seconds — or minutes — later, from wherever they are.
A proposed action carries a **TTL** (default 10 minutes, bounded between 60 seconds and 24 hours). If the user does not act before the TTL lapses, the card **expires**. There is no negative attestation on a timeout:
**TTL is cancel. Silence is not consent.** A card that ages past its TTL produces **no** Proof of Resolution. The agent receives an expiry signal — "the user did not respond in time, stand down." A failed biometric is the same class: an *absence* of attestation, never a denial.
A **Deny** is different from an expiry: it is an explicit verdict, and it *does* produce a signed Proof of Resolution (verdict `denied`) so the agent can prove the user actively refused.
## Who an agent can propose to
Q only requires that the target be a **registered BotShield user** — `agentlink/inquire` resolves the user and queues a card; it does **not** hard-reject a user who has no linked Trusted Account. A linked **Trusted Account** is *recommended*: it is a V2.1 routing input that lets the agent target a specific account (via `trusted_account_id`) and strengthens MultiPass durability, but it is optional. See [Agent Integration](/queue/agent-integration#prerequisites).
## Privacy boundary
Q inherits BotShield's privacy architecture. Identity (the user's email) lives only in the consumer app, behind Clerk — it **never crosses the agent or partner boundary**.
* **Q card contents are shown to the user only.** The agent and your backend never receive the card body back. The Proof of Resolution confirms the *verdict*; it does not echo what the user saw.
* Before a card is queued, its visual payload (an Adaptive Card) passes the **TRUST Layer** — a schema allow-list plus a semantic judge plus a regex backstop — so a malicious agent can't smuggle a phishing prompt onto the user's lock screen.
## Where to go next
Register a Trusted Agent and propose your first action.
The full lifecycle: BotShield Q push → Confirm → Proof of Resolution, with all card states.
The ES256 JWT — claims, JWKS verification, and webhook events.
Every `agentlink/*` operation with request and response shapes.