Skip to main content
The Personal Agent Protocol (“Poppy”) lets a person’s own agent find your company, sign in with scopes, and act on their behalf. Poppy is a protocol, not a package: your company publishes a 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

The assistant 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, on app.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.
The 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:
The model reads the text, tells the user, and calls the tool again. A client that supports the extension repeats the call with 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.
The package covers only BotShield’s part. You still need your Poppy core: 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.