Proof of Resolution

A Proof of Resolution is the artifact Q produces when a user resolves a Q card with a biometric. It is a JSON Web Token signed with ES256 (EC P-256, asymmetric) — a portable, action-scoped, independently verifiable attestation of the user’s verdict. Because it is signed with a private key whose public counterpart is published as a JWKS, an agent or your backend can verify a Proof of Resolution locally, with no round-trip to BotShield.

The token carries a verdict of approve or denied — both are signed. An expired or cancelled card produces no token at all. See Resolution Flow.

Claims

The token’s header carries alg: ES256 and kid: v2. The payload claims:

{
  "iss": "https://api.botshield.ai",
  "sub": "b5e1…",
  "aud": "a9f2…",
  "iat": 1750075200,
  "exp": 1750161600,
  "jti": "3f1b2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "verdict": "approve",
  "action": {
    "category": "travel.book",
    "description": "Book Uber to SFO",
    "trusted_account_id": "7a8b9c0d-…"
  },
  "kid": "v2",
  "ceremony_id": "e4d3c2b1-…"
}

Claim	Meaning
`iss`	Always `https://api.botshield.ai`.
`sub`	The BotShield user who confirmed (an opaque internal id — not an email or identity).
`aud`	The Trusted Agent the token is issued to. Verify this matches your agent.
`iat` / `exp`	Issued-at and expiry (Unix seconds). Tokens live 24 hours — redeem within that window.
`jti`	The `request_id` you supplied to `inquire`. Your join key.
`verdict`	`approve` or `denied` — the user’s decision.
`action`	The sanitized action context the user saw — `category`, `description`, optional `trusted_account_id`, `total`, `total_currency`. Not the full Adaptive Card.
`kid`	Key id, currently `v2`. Selects the JWKS key for verification.
`ceremony_id`	Present when several cards were confirmed in one biometric ceremony. Cards sharing a `ceremony_id` (and an identical `iat`) were authorized in a single act.

The Proof of Resolution carries no identity. sub is an opaque BotShield user id; there is no email, no device identifier, and no Adaptive Card body. It attests the verdict on a specific action, nothing more.

Verify locally with the JWKS

BotShield publishes the Resolution public key as a JWK Set at:

https://api.botshield.ai/.well-known/jwks.json

The kid in the JWKS matches the JWT header, so verification is the standard JWKS flow. This is the recommended path — no network call to BotShield per verification.

Node

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://api.botshield.ai/.well-known/jwks.json")
);

async function verifyProof(token: string, myAgentId: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: "https://api.botshield.ai",
    audience: myAgentId,            // must match your registered agent
    algorithms: ["ES256"],
  });

  // jwtVerify already enforced signature, iss, aud, and exp.
  if (payload.verdict !== "approve" && payload.verdict !== "denied") {
    throw new Error(`unexpected verdict: ${payload.verdict}`);
  }

  return payload; // { jti: request_id, verdict, action, ceremony_id, … }
}

Always check verdict === "approve" before acting — a denied token is a valid, signed refusal, not an authorization.

Verify via the SDK (coming)

A round-trip verifier — sdk/verify-resolution, for callers who prefer not to pin a JWKS client — is planned but not yet available. It will perform the same ES256 verification server-side (rejecting bad signatures, wrong issuer, expired tokens, or an invalid verdict) and return the decoded claims.

Until it ships, local JWKS verification (above) is the supported path — and it is sufficient: it enforces signature, issuer, audience, expiry, and algorithm entirely client-side with no network round-trip.

Key rotation

The kid header tags the key version (today v2). When BotShield rotates keys, the new key is appended to the JWKS under a new kid; the old key is retained until all tokens signed with it expire (24-hour TTL). A correct JWKS verifier selects the key by kid automatically — no action required on rotation. Pin algorithms: ["ES256"] to reject any token that claims a different algorithm.

Webhook events

In addition to (or instead of) polling, Q delivers events to your endpoint via Svix. Each delivery is signed with your endpoint’s whsec_ secret and carries the svix-id / svix-timestamp / svix-signature headers — verify exactly as described in Webhooks.

Not yet firing in the current build. The q.card.proposed and q.resolution.* events are defined as below, but they do not yet fire for agent-proposed cards — partner organization association for the Q flow is still being wired up. Until that lands, use polling (check-status) as the reliable way to learn an outcome. The schemas here are stable; treat the webhook path as forthcoming.

Event (`type`)	Fires when
`q.card.proposed`	An agent proposed an action; a Q card was created and pushed to the user.
`q.resolution.confirmed`	The user confirmed the action (Proof of Resolution issued, verdict `approve`).
`q.resolution.denied`	The user denied the action (Proof of Resolution issued, verdict `denied`).
`q.resolution.expired`	The card’s TTL lapsed before the user acted — no Proof of Resolution.

`q.card.proposed`

{
  "type": "q.card.proposed",
  "request_id": "3f1b2c4d-…",
  "card_id": "c1d2e3f4-…",
  "agent_id": "a9f2…",
  "agent_name": "ticketz-agent",
  "category": "travel.book",
  "summary_title": "Book Uber to SFO",
  "ttl_at": "2026-06-16T12:10:00Z"
}

`q.resolution.confirmed` / `q.resolution.denied`

{
  "type": "q.resolution.confirmed",
  "request_id": "3f1b2c4d-…",
  "resolution_id": "r0a1b2c3-…",
  "outcome": "confirmed",
  "proof_token": "eyJhbGciOiJFUzI1Ni␣…",
  "metadata": {
    "card_id": "c1d2e3f4-…",
    "ceremony_id": "e4d3c2b1-…",
    "agent_id": "a9f2…",
    "agent_name": "ticketz-agent"
  }
}

outcome is confirmed for q.resolution.confirmed and denied for q.resolution.denied. The proof_token field carries the Proof of Resolution JWT — verify it as above before acting. When several cards were confirmed in one ceremony, each fires its own message, all sharing one ceremony_id in metadata.

`q.resolution.expired`

{
  "type": "q.resolution.expired",
  "request_id": "3f1b2c4d-…",
  "card_id": "c1d2e3f4-…",
  "outcome": "expired",
  "metadata": {
    "agent_id": "a9f2…",
    "agent_name": "ticketz-agent",
    "summary_title": "Book Uber to SFO"
  }
}

No proof_token — there is no signed verdict on an expiry. Treat it as “stand down.”

Authenticity comes from the Svix envelope signature, verified with your whsec_ endpoint secret — not from a token inside the webhook. For confirmed/denied events you then independently verify the proof_token JWT. Dedupe on the Svix message id for idempotency; BotShield may retry.

Next steps

Q API Reference

Every agentlink/* operation with request and response shapes.

Webhooks

The shared Svix signature-verification pattern, with per-language snippets.

Get Started

Client SDK Embed

Server SDK

Integration Guides

Deployment

Queue (Q)

Concepts

Proof of Resolution

Proof of Resolution

Claims

Verify locally with the JWKS

Node

Verify via the SDK (coming)

Key rotation

Webhook events

`q.card.proposed`

`q.resolution.confirmed` / `q.resolution.denied`

`q.resolution.expired`

Next steps

Q API Reference

Webhooks

​Proof of Resolution

​Claims

​Verify locally with the JWKS

​Node

​Verify via the SDK (coming)

​Key rotation

​Webhook events

​q.card.proposed

​q.resolution.confirmed / q.resolution.denied

​q.resolution.expired

​Next steps

Q API Reference

Webhooks

Proof of Resolution

Claims

Verify locally with the JWKS

Node

Verify via the SDK (coming)

Key rotation

Webhook events

`q.card.proposed`

`q.resolution.confirmed` / `q.resolution.denied`

`q.resolution.expired`

Next steps