poppy.json, verifies each request’s signed Poppy Session, and runs Poppy’s OAuth sign-in.
For an action that is hard to undo, an agent’s statement that “the user approved” is not the user approving. BotShield gives your company its own channel to the account holder: they answer on their own phone, in the BotShield app, with their passkey, and your server receives a signed answer. The agent never holds the passkey, so it cannot produce an approval.
What your company gets
Both are live in production today, through BotShield’s extensions for Poppy. Each extension is optional: an agent that does not support one ignores it, and still sees an ordinary error that tells it what to do.
botshield.ai/approval
Use it when the holder of the account must say yes to specific terms: change a plan, add a payee, refund to a different card.
- You send the request for approval through BotShield, to the account holder, whose account is BotShield Verified (see BotShield Verified). They see your company’s name, a summary and the terms rows, and approve with their passkey.
- BotShield gives your server a signed answer (an ES256 JWT) for that one request. It names no person: no name, email, phone number or account reference.
- The answer is good once. Your server checks it with BotShield, which refuses it a second time, and performs the action at most once, however often the agent repeats its request.
- Only an account that is BotShield Verified with you can be asked. In a signed-out session, or for an account that isn’t BotShield Verified, you handle the action as you would without the extension.
The BotShield Signal API, at each order
Theassistant Action of botshield.ai/approval. The first time, the account holder approves the customer’s assistant once for your company (“Let buy for you”, one request in the BotShield app, with their passkey). After that, your server checks at every order and gets verified: true, and nobody waits. The account holder can remove the assistant in the app, and the next check answers false. See BotShield Signal API.
Signed-out sessions: botshield.ai/human-presence
For a session with no signed-in account, your gate can ask for a passkey confirmation on the phone instead, for example to hold an entry to one per verified phone number.
- You open the check at one of your gates. Your answer carries one link,
verification_uri, onapp.botshield.ai. The agent shows the link, or a QR code of it on a computer, and never opens it itself. - Your company learns pass or refused at its own gate, under the rule you set. It gets no identifier, nothing it could match with another company.
- It is not the account holder’s approval. For a signed-in account, use
botshield.ai/approval.
How it works
1
The agent asks
The agent calls your API or MCP tool. A Poppy agent that supports the extension declares it:
2
Your company answers 403 and asks the account holder
Nothing is done yet. Your server asks the account holder through BotShield and answers with an approval object (or a presence object):
3
The account holder answers on their phone
In the BotShield app, with their passkey. The agent tells the user to check the app, and never handles the answer.
4
The agent repeats its request
The same request, no sooner than
retry_after seconds, with the header BotShield-Approval-Id: apv_8Hq2Lk (or BotShield-Presence-Id for presence). Your server checks BotShield’s signed answer and acts, once.state of an approval is requested, approved, declined or expired. A presence check is requested, passed, refused (the gate’s rule refused it, for example under a one-per-number rule) or expired. declined, refused and expired say nothing about the account holder beyond what the agent could already see.
Any MCP client, not only Poppy
On an MCP server, the tool returns an error result (isError: true) with the approval or presence object in structuredContent, and text written for any MCP client, including one that knows nothing about Poppy or these extensions:
botshield.ai/approval-id (or botshield.ai/presence-id) in the call’s _meta. Either way, your server performs the action only after verifying the approval.
What each side learns
Your side, in Node.js
Install@botshield/poppy from npm. It does your company’s side of both extensions on your server: AccountHolderApproval and HumanPresence, the HTTP and MCP responses, and the BotShield calls. It uses your secret key, has no runtime dependencies, and needs Node.js 20 or later. The source, both specifications and a demo are open source in Bot-Shield/poppy-extensions.
Use
@botshield/poppy 0.2.0 or later. Server confirmation of BotShield Verified (confirmLink) and Cloudflare Workers support arrived in 0.2.0; 0.1.0 does not run on Workers.poppy.json, verifying the signed Poppy Session, and Poppy’s OAuth sign-in.
See it live
The live demo is a ticket seller that speaks Poppy and uses both extensions: a refund to a different card that the account holder approves, and a passkey check at a gate. It shows each step as it happens, on the agent, the company and BotShield.Next steps
Set up
Keys, gates,
poppy.json, server code and the test checklist.BotShield Signal API
Approve a customer’s assistant once, check it at every checkout.
Verified Accounts
How a customer gets BotShield Verified, which approval needs first.
Who may pass
The rules a gate applies to a passkey check.
Open source
The specifications, the package and the demo.
