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(thematchfield) means the account holder approved this assistant for this account: itsclient_idand, 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 withbotshield.ai/approval.- An answer is for one order. Check every order. Each answer carries its own
checked_atandcheck_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 asbotshield.ai/approval, with one Action for the assistant:
-
A secret key with Gates API access (
bs_dev_…to start). See Setup, step 1. - A Trusted Agent whose agent name the request is shown under. Any category: Actions requests don’t use it. See Setup, step 2.
-
An Action with the key
assistant. Place it in the Console under Verified Accounts › BotShield Actions, or with the Gates API: - 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.
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_idandsubfrom the verified Poppy Session. Without Poppy, pass theclientIdyou know and nouserId. - The agent sees the usual
account_holder_approval_requiredresponse with an approval object, tells the user to approve in the BotShield app, and repeats its request withBotShield-Approval-Id. In an MCP tool, returnapprovalToolResult(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, andstore. With more than one server, pass a sharedstore, as forAccountHolderApproval. The store holds the pairwise ID. - A customer whose account is not BotShield Verified can’t be asked:
require()throws aBotShieldErrorwithcodenot_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 athttps://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_idis the assistant’s Poppyclient_id, the HTTPS URL of its metadata, from the verified Poppy Session.assistant_user_idis the Session’ssub, when it has one.pairwise_idis yours to keep. Never give it to the assistant.- With no approval yet,
check_assistantanswers false: callrequest_assistant_approval.
API operations
Both need a secret key with Gates API access, asAuthorization: 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.
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.
