Skip to main content
The BotShield Signal API, for agentic commerce, tells your server whether the agent placing an order is bound to a BotShield Verified customer: its account holder approved it, with a passkey. Your server asks at each order and gets a fresh answer, verified: true or false. After the account holder’s one-time approval, nobody is asked at an order. BotShield is not the checkout, the wallet or the card: the wallet pays and your server places the order. When a customer’s assistant buys at your company, you want to know that this is the assistant the account holder said may buy for them. The account holder approves the assistant once per company, in the BotShield app, with their passkey. At every checkout after that, your server asks BotShield: is this the assistant the account holder approved? BotShield answers verified, true or false, fresh, for that order. It is the assistant Action of botshield.ai/approval: the same extension and the same 403 response to the agent. Only what the account holder approves changes. Nothing new for your customer: they approve in the BotShield app they already use to be BotShield Verified with you, and their agent needs no BotShield account or credential. Your company connects its own server to BotShield.

How it works

1

The first checkout asks the account holder

The first time an assistant buys for a customer at your company, you ask the account holder to approve it. They get one request in the BotShield app, Let buy for you, with rows naming the assistant and where it comes from, and approve with their passkey.AssistantGate and the MCP tools read the assistant’s name from the client_name in its OAuth Client ID Metadata Document, fetched from its client_id URL. When BotShield records the approval, it reads that document again, and refuses unless the title the account holder approved is Let buy for you. If you build the request yourself, use that exact title.
2

BotShield records the approval

Once the account holder approves, BotShield reads the assistant’s metadata again and records the approval only if the name the person saw is still the assistant’s client_name. Your server receives BotShield’s pairwise ID for this approval: one company, one account, one assistant (client_id) and, under Poppy, that assistant’s user ID for your company (sub).
3

Every checkout is checked

At each checkout, after you verify the Poppy Session, your server asks BotShield with the account, the pairwise ID or the assistant’s client_id, the assistant’s user ID, and your own reference for the order. BotShield answers verified, true or false (match in the response), with a time and a check ID. The person is not asked again.
4

The person can remove the assistant

The person sees each approved assistant under your company in the BotShield app and can remove it. Every check after that answers false, and your next checkout asks the account holder again.

What verified: true means

  • verified: true (the match field) means the account holder approved this assistant for this account: its client_id and, when you send it, its user ID for your company. It is only as strong as your own verification of the request’s Poppy signature. It is not consent to an order’s terms. When you want the account holder to approve what is being bought (the items, the total, the address), ask for that action itself with botshield.ai/approval.
  • An answer is for one order. Check every order. Each answer carries its own checked_at and check_id.
  • False carries no reason. Whether the assistant was never approved, was removed, or is a different assistant, the answer is the same.
  • The pairwise ID is yours. Keep it on your server. Never give it to the assistant.
  • BotShield records each check (your company, the time, the result), never what was bought. Your order reference is recorded hashed.

Set up

You need the same setup as botshield.ai/approval, with one Action for the assistant:
  1. A secret key with Gates API access (bs_dev_… to start). See Setup, step 1.
  2. A Trusted Agent whose agent name the request is shown under. Any category: Actions requests don’t use it. See Setup, step 2.
  3. An Action with the key assistant. Place it in the Console under Verified Accounts › BotShield Actions, or with the Gates API:
  4. BotShield Verified customers. Only the holder of a Verified Account can approve an assistant. Get each customer BotShield Verified once, as in Setup, step 6.
The assistant’s metadata must be readable: its client_id is an https:// URL on a DNS name, the document answers 200 without a redirect, its client_id field matches, and its client_name is 1 to 60 characters. If AssistantGate or the MCP tools can’t read the name, the account holder is not asked. If BotShield can’t read it when recording the approval, register answers not_approved.

In Node.js: AssistantGate

AssistantGate in @botshield/poppy does your company’s side: it asks the account holder the first time, records the approval, keeps the pairwise ID in its store, and checks at every checkout. It needs @botshield/poppy 0.2.x or later. Source: Bot-Shield/poppy-extensions.
  • Pass the assistant’s client_id and sub from the verified Poppy Session. Without Poppy, pass the clientId you know and no userId.
  • The agent sees the usual account_holder_approval_required response with an approval object, tells the user to approve in the BotShield app, and repeats its request with BotShield-Approval-Id. In an MCP tool, return approvalToolResult(r.approval) instead.
  • After the person removes the assistant, the next check answers false and require() asks the account holder again.
  • Options: ttlSeconds (60–86400, default 600), retryAfter, checkEvery, and store. With more than one server, pass a shared store, as for AccountHolderApproval. The store holds the pairwise ID.
  • A customer whose account is not BotShield Verified can’t be asked: require() throws a BotShieldError with code not_linked, and nothing is sent.

From your own agent: Partner MCP tools

If your company’s own agent speaks MCP, it can use three tools on the hosted server at https://mcp.botshield.ai/mcp, authenticated with your company’s secret key with Gates API access, Authorization: Bearer bs_… (not an agent key). See MCP server for connecting a client.
  • assistant_client_id is the assistant’s Poppy client_id, the HTTPS URL of its metadata, from the verified Poppy Session. assistant_user_id is the Session’s sub, when it has one.
  • pairwise_id is yours to keep. Never give it to the assistant.
  • With no approval yet, check_assistant answers false: call request_assistant_approval.

API operations

Both need a secret key with Gates API access, as Authorization: Bearer bs_…. Errors arrive in data.error with HTTP 200, as for the rest of the Gates API: statusCode in the tables below is a field of data.error, not the HTTP status. The check’s answer is not signed, so call it only server to server, over TLS, and keep check_id with the order. Before you register, ask the account holder with gates-api/actions/request (act assistant: followed by BotShield’s digest of the assistant) and read gates-api/actions/request-status until it is approved. AssistantGate and the MCP tools build that request for you; use them rather than building the act yourself.

POST /gates-api/assistants/register

Records an approved request and returns BotShield’s pairwise ID.
BotShield checks that the request is yours, in your key’s environment, and approved; that it names this assistant and this user; that the person who approved holds this account’s live BotShield link; and that the title they approved is “Let buy for you” with the name BotShield reads now from the assistant’s metadata. Every miss answers the same not_approved (404). The call is idempotent: the same approved request returns the same ID. A new approval for the same account and assistant replaces the earlier one, and keeps the same pairwise ID: the ID is derived from your company, the environment, the account, the client_id and the user ID.

POST /gates-api/assistants/check

match carries the answer: true means the agent is verified, false means it isn’t. Verified needs a live approval, this account, the same assistant, and the same user ID (both absent, or both equal). A request that fails validation (a malformed pairwise_id, a client_id that isn’t a URL, an order_ref over 256 characters) returns HTTP 400 with a validation body instead of the data.error envelope. Re-asking: with onUnapproved: 'ask' (the default), each require() without a BotShield-Approval-Id after a decline or expiry starts a new request, within the limits above. Use onUnapproved: 'signal' to never ask from require(), and ask() when you choose. These operations are not in botshield-sdk 4.0.1. Call them over HTTP, or use AssistantGate.

What each side learns

Next steps

Set up

Keys, the Trusted Agent, BotShield Verified customers and poppy.json.

Personal agents (Poppy)

The two extensions and what each side learns.