Proof of Resolution

A Proof of Resolution is the signed result of a decided action. It is a JWT signed by BotShield with ES256, issued when a human gives a Confirm or a Deny with their device biometric. You verify it locally against BotShield’s public keys, check that it belongs to your agent and your request, and only then execute.

Both decisions are signed: a Confirm carries verdict: "approve" and a Deny carries verdict: "denied". An Expired or cancelled proposal produces no proof at all. Absence of a proof is never permission.

Token format

Header:

{
  "alg": "ES256",
  "kid": "v2",
  "typ": "JWT"
}

Payload:

{
  "iss": "https://api.botshield.ai",
  "sub": "OP_QDhs65484684",
  "aud": "a9f2c6d4-1b7e-4f3a-9c58-2e6d0b4a7f11",
  "iat": 1790012611,
  "exp": 1790099011,
  "jti": "3f1b2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "verdict": "approve",
  "action": {
    "category": "travel.refund",
    "description": "Refund booking MA-48213 to your Visa ending 4242",
    "trusted_account_id": null
  },
  "kid": "v2",
  "ceremony_id": "e4d3c2b1-0f9e-4d8c-b7a6-5f4e3d2c1b0a"
}

Claim	Meaning	What to check
`iss`	Always `https://api.botshield.ai`.	Equals that value.
`sub`	The pairwise `opaque_id` (`OP_…`) your agent holds for the human who decided. Never a global user id, a name, or an email.	Equals the `opaque_id` you proposed to.
`aud`	Your agent’s Agent ID (a UUID). The proof is issued to one agent.	Equals the Agent ID you copied from the Console. See Find your agent’s id.
`jti`	The `request_id` you sent to `POST /agentlink/inquire`.	Equals the request you are about to execute, and has not been executed before.
`verdict`	`approve` for a Confirm, `denied` for a Deny.	Is exactly `approve` before you execute.
`action.category`	The category you proposed.	Matches the action you are about to run.
`action.description`	The `summary_title` the human saw.	Optional: compare with what you sent.
`action.trusted_account_id`	The value you sent, or `null`.	—
`iat`	When the human decided, in Unix seconds.	—
`exp`	`iat` plus 24 hours.	Not in the past. Redeem the proof within a day.
`kid`	The signing key id, also in the header. Currently `v2`.	Let your JWT library select the key by `kid`. Do not hard-code it; keys rotate.
`ceremony_id`	Identifies the biometric confirmation. When a person decides several cards at once, those proofs share a `ceremony_id` and an identical `iat`.	—

The proof carries no personal data and does not include the Adaptive Card body.

Public keys

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

The JWK Set holds EC P-256 public keys with alg: "ES256", use: "sig", and a kid. It is served with a 5-minute cache lifetime, so cache it for 5 minutes and refetch when you meet an unknown kid. The same key set signs BotShield Gate attestation tokens.

Verify before you execute

Verification is local. There is no BotShield endpoint to call and nothing to trust except the signature. Install jose and verify:

npm install jose

import { createRemoteJWKSet, jwtVerify } from "jose";

const ISSUER = "https://api.botshield.ai";

// Fetches and caches the key set; refetches on an unknown kid.
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`), {
  cacheMaxAge: 5 * 60 * 1000,
});

interface Expected {
  agentId: string;   // your Agent ID, copied from the Console into config
  requestId: string; // the request_id you proposed with
  opaqueId: string;  // the opaque_id you proposed to
  category: string;  // the category you proposed
}

/** Returns true only when a verified human confirmed exactly this request. */
export async function isConfirmed(token: string, expected: Expected): Promise<boolean> {
  let payload;
  try {
    // Verifies the signature and rejects a wrong issuer, a wrong audience,
    // an expired token, or any algorithm other than ES256.
    ({ payload } = await jwtVerify(token, JWKS, {
      algorithms: ["ES256"],
      issuer: ISSUER,
      audience: expected.agentId,
    }));
  } catch {
    return false;
  }

  if (payload.jti !== expected.requestId) return false;
  if (payload.sub !== expected.opaqueId) return false;

  const action = payload.action as { category?: string } | undefined;
  if (action?.category !== expected.category) return false;

  return payload.verdict === "approve";
}

Use it as the gate in front of the action:

const pending = await db.refunds.findByRequestId(requestId); // your own record

const ok = await isConfirmed(resolutionJwt, {
  agentId: process.env.BOTSHIELD_AGENT_ID!,
  requestId: pending.requestId,
  opaqueId: pending.opaqueId,
  category: "travel.refund",
});

if (!ok) return; // denied, expired, tampered, or not yours: do nothing

// Execute once per jti, even if the proof arrives twice (poll + webhook).
const first = await db.refunds.markExecuted(pending.requestId);
if (first) await issueRefund(pending);

Run this check in deterministic code on your server, at the point where the action executes. A language model cannot verify a signature, and a status string is not proof. Compare against your own stored request_id, opaque_id, and category, not against values the agent hands you alongside the token.

Find your agent’s id

aud is the Agent ID: the UUID BotShield assigned to your agent, not its name. Copy it from the BotShield Console:

Go to Agents Ask → Trusted Agents and select the environment with the Development | Production toggle.
Find the agent’s row. The Agent ID is shown under the agent name.
Click the copy button next to it.

Store the value in configuration next to the agent key (the example above reads it from BOTSHIELD_AGENT_ID), and pin audience to it. Treat it as configuration, not as a value you read from the token or from the agent at run time: the check is only worth something when the expected audience comes from you.

A development agent and a production agent have different Agent IDs, so configure each environment with its own.
The Agent ID stays the same when you rotate the agent’s key. A proof issued before a rotation still verifies against the same audience.
An agent you register after revoking an old one has a new Agent ID, even if it reuses the name. Update the audience when you replace an agent.

The same value appears in the webhooks your organization receives, as agent_id in every agents_ask.card.proposed payload and as metadata.agent_id in every agents_ask.resolution.* payload. Use it there to tell which agent an event belongs to.

How the proof reaches you

The same token is delivered two ways. Verify it the same way on both, and make execution idempotent on jti, because you may receive it twice.

Poll check-status
Webhooks

GET /agentlink/check-status returns the token as resolution_jwt once the status is approved or denied. It is null for queued, expired, and cancelled.

{
  "data": {
    "data": {
      "status": "approved",
      "ttl_at": "2026-09-21T17:52:10.000Z",
      "resolved_at": "2026-09-21T17:43:31.412Z",
      "ceremony_id": "e4d3c2b1-0f9e-4d8c-b7a6-5f4e3d2c1b0a",
      "resolution_jwt": "eyJhbGciOiJFUzI1NiIsImtpZCI6InYyIn0…",
      "verdict": "approve",
      "delivered": false,
      "callback_attempts": 0
    }
  }
}

See Wait for the decision.

agents_ask.resolution.confirmed and agents_ask.resolution.denied carry the token as proof_token.

{
  "type": "agents_ask.resolution.confirmed",
  "request_id": "3f1b2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "resolution_id": "5c0a7e1d-93b2-4f6e-8a44-d1e2f3a4b5c6",
  "outcome": "confirmed",
  "proof_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6InYyIn0…",
  "metadata": {
    "card_id": "0b9d6c0e-7a57-4c55-9a53-0a1f4c1d2e3f",
    "ceremony_id": "e4d3c2b1-0f9e-4d8c-b7a6-5f4e3d2c1b0a",
    "agent_id": "a9f2c6d4-1b7e-4f3a-9c58-2e6d0b4a7f11",
    "agent_name": "MeridianConcierge"
  }
}

agents_ask.resolution.expired has outcome: "expired", a card_id, and no proof_token:

{
  "type": "agents_ask.resolution.expired",
  "request_id": "3f1b2c4d-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "card_id": "0b9d6c0e-7a57-4c55-9a53-0a1f4c1d2e3f",
  "outcome": "expired",
  "metadata": {
    "agent_id": "a9f2c6d4-1b7e-4f3a-9c58-2e6d0b4a7f11",
    "agent_name": "MeridianConcierge",
    "summary_title": "Refund booking MA-48213 to your Visa ending 4242"
  }
}

Add endpoints in the BotShield Console under Settings → Developer Tools → Webhooks, and verify each delivery’s signature before you read the body. See Webhooks and Webhook events.

Verify the webhook signature and the proof_token. The webhook signature proves BotShield sent the delivery to you. The proof proves what the human decided, and it stays verifiable after you store it or pass it to another system.

Outcomes at a glance

State	`status`	Proof	Webhook	What your code does
Confirmed	`approved`	Yes, `verdict: "approve"`	`agents_ask.resolution.confirmed`	Verify, then execute once.
Denied	`denied`	Yes, `verdict: "denied"`	`agents_ask.resolution.denied`	Do not execute. Keep the proof as evidence of the refusal.
Expired	`expired`	None	`agents_ask.resolution.expired`	Do not execute. Propose again with a new `request_id` if it still matters.
Cancelled by your agent	`cancelled`	None	—	Nothing to do.

Keep the proof

Store the token with the record of the action it authorized. It is a self-contained, independently verifiable record that a verified human confirmed that exact request, which is useful for disputes and audits. Verify it when it arrives and record the result and the time next to it: after exp the token no longer passes a standard JWT verification.

Next steps

Propose an action

Where request_id, verdict, and resolution_jwt come from.

Webhook events

Full payloads for the agents_ask.* events.

Privacy boundary

Why sub is an opaque, per-agent id.

agentgateway

Use BotShield with agentgateway in front of your agent’s tools.

Get Started

BotShield Gate

Trusted Accounts

Agents Ask

Webhooks

Console

Server SDK

Integrations

Concepts

Changelog

Token format

Public keys

Verify before you execute

Find your agent’s id

How the proof reaches you

Outcomes at a glance

Keep the proof

Next steps

Propose an action

Webhook events

Privacy boundary

agentgateway

​Token format

​Public keys

​Verify before you execute

​Find your agent’s id

​How the proof reaches you

​Outcomes at a glance

​Keep the proof

​Next steps

Propose an action

Webhook events

Privacy boundary

agentgateway

Token format

Public keys

Verify before you execute

Find your agent’s id

How the proof reaches you

Outcomes at a glance

Keep the proof

Next steps