Skip to main content

​
BotShield Queue (Q)

BotShield Queue — Q — is the agentic product. Where Census 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:

Agent-agnostic

The proof is produced by BotShield, not the agent. Any agent — or your backend — verifies it the same way.

Hardware-backed

The verdict is signed only after a real Face ID / Touch ID ceremony fires the device’s Secure Enclave passkey.

Action-scoped

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.

Independently verifiable

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

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

​
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

Agent Integration

Register a Trusted Agent and propose your first action.

Resolution Flow

The full lifecycle: BotShield Q push → Confirm → Proof of Resolution, with all card states.

Proof of Resolution

The ES256 JWT — claims, JWKS verification, and webhook events.

Q API Reference

Every agentlink/* operation with request and response shapes.