> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botshield.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Personal agents (Poppy)

> Know that the agent placing an order belongs to a verified customer, and get the account holder's signed approval of exact terms, through the Personal Agent Protocol.

The [Personal Agent Protocol](https://personalagentprotocol.org) ("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

| | When | Your company gets |
| - | - | - |
| [**BotShield Signal API**](https://docs.botshield.ai/poppy/agentic-checkout.md) | An agent places an order | **verified: true** or **false**: the agent is bound to a BotShield Verified customer. Nobody is interrupted. |
| **Agents Ask**, through `botshield.ai/approval` | The customer must decide | The **account holder** approved these **exact terms**, on their own phone, with their passkey. A signed approval, or a plain no. |

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](https://docs.botshield.ai/verified-accounts/overview.md)). 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 {assistant} 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](https://docs.botshield.ai/poppy/agentic-checkout.md).

### 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:

```http theme={null}
POST /plans/change HTTP/1.1
Poppy-Extensions: "botshield.ai/approval";v="1"
```

**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):

```http theme={null}
HTTP/1.1 403 Forbidden
Content-Type: application/json
Retry-After: 5

{
  "error": "account_holder_approval_required",
  "error_description": "The account holder has been asked to approve this in the BotShield app.",
  "approval": {
    "approval_id": "apv_8Hq2Lk",
    "state": "requested",
    "summary": "Change your plan to **Unlimited Plus**, from your next bill.",
    "terms": [
      { "label": "Plan", "value": "Unlimited Plus" },
      { "label": "Total", "value": "$95.00 a month" }
    ],
    "expires_at": "2026-11-18T17:05:00Z",
    "retry_after": 5,
    "operation_hash": "…"
  }
}
```

**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:

```json theme={null}
{
  "isError": true,
  "content": [{ "type": "text", "text": "Not done yet. The account holder needs to approve this in the BotShield app on their phone: change your plan to Unlimited Plus. Call this tool again after they approve." }],
  "structuredContent": { "approval": { "approval_id": "apv_8Hq2Lk", "state": "requested", "…": "…" } }
}
```

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

| | Learns |
| - | - |
| The agent | That the account holder was asked, or that a passkey check is needed, and how it ended. Nothing about who they are. |
| Your company | A signed yes for these terms, or pass or refusal at your gate. No identifier for the person beyond a pairwise ID only your company holds. |
| BotShield | That your company asked, and the answer. Under `approval`, not which agent asked. Under the [BotShield Signal API](https://docs.botshield.ai/poppy/agentic-checkout.md), the assistant's `client_id` and, when you send it, its user ID for your company, stored as a hash. |

## Your side, in Node.js

Install [`@botshield/poppy` from npm](https://www.npmjs.com/package/@botshield/poppy). 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](https://github.com/Bot-Shield/poppy-extensions).

```bash theme={null}
npm install @botshield/poppy
```

> [!NOTE]
>
> 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](https://poppy-demo.couchtour.app) 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

> [card] [Set up](https://docs.botshield.ai/poppy/setup.md)
>
> Keys, gates, `poppy.json`, server code and the test checklist.

> [card] [BotShield Signal API](https://docs.botshield.ai/poppy/agentic-checkout.md)
>
> Approve a customer's assistant once, check it at every checkout.

> [card] [Verified Accounts](https://docs.botshield.ai/verified-accounts/overview.md)
>
> How a customer gets BotShield Verified, which approval needs first.

> [card] [Who may pass](https://docs.botshield.ai/gate/who-may-pass.md)
>
> The rules a gate applies to a passkey check.

> [card] [Open source](https://github.com/Bot-Shield/poppy-extensions)
>
> The specifications, the package and the demo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.