---
title: Personal Agent Protocol
description: Why the shop uses Poppy, and how Sessions, grants and agent channels fit together.
sidebar:
  order: 3
  label: Poppy overview
---

Personal Agent Protocol (Poppy) describes how software acting for a person works with a company on that
person's behalf. This shop implements the company side of draft 0.1. The
[protocol specification](https://personalagentprotocol.org/docs/spec) defines the wire format; this page explains
the model and points to the implementation documentation.

## Why it is part of this demo

An agent needs its own identity and permissions instead of borrowing a person's credentials. Poppy connects
that identity across APIs, a browser and conversations with the company. A person can approve access, see which
agent acted, and revoke its grant. Account Tokens let the agent return for later tasks without asking the person
to sign in each time.

## Sessions and grants

| Concept        | Role                                                                                                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Personal Agent | Software acting for one User. Its client ID is the URL of its metadata document, which identifies its signing keys.                                                                         |
| Company        | The shop, with discovery at `/.well-known/poppy.json`, published resources and a Company Agent called Fern.                                                                                 |
| Session        | One agent's interaction with the Company for a User. It starts identified but signed out; signing in gives it account permissions.                                                          |
| Account Token  | A credential for returning with an approved account grant. Ending one Session leaves this grant usable; disconnecting the grant revokes it and its Sessions.                                |
| Permissions    | `poppy:read` for account reads, `poppy:write` for supported changes, and `checkout` for purchases with a saved card. Effective authority is limited by both the token and the live Session. |
| Channels       | Direct API calls, MCP, an agent browser and conversations share the Session's identity and authority. Signed-in agents use the account cart; signed-out agents use a Session cart.          |

The protocol defines Direct, Device and Mediated sign-in. The Auth0 proxy handles these flows, grants and Sessions
alongside Auth0; it issues credentials and answers introspection. The Shop API owns the shared commerce operations,
conversations and Fern. The storefront owns browser sessions and UI. The MCP server adapts tools to the Shop API.
The Auth0 proxy never proxies commerce traffic.

An agent browser joins a Poppy Session through a signed browser assertion. The shop sets its browser cookie and
shows the agent banner. The cookie carries the Poppy Session's authority; it does not become an Auth0 browser
sign-in. The account's Sessions page combines the two sources so the person can manage them together.

## First sign-in

An agent first discovers the Company and creates an identified, signed-out Session. It can use permitted base
capabilities before it has account access. Direct sign-in uses an authorization-code flow with PKCE; Device sign-in
lets the person approve the request in their own browser. The protocol also defines Mediated sign-in.

After the person signs in and approves scopes, the agent receives an Account Token and Session credentials for the
approved account. Later tasks can use the Account Token to sign in a Session without repeating approval. Direct API
calls use DPoP-bound credentials; MCP uses credentials for the exact MCP resource. An agent browser joins through
a browser assertion. These channels preserve the same Session authority.

Ending one Session ends that interaction. Disconnecting the account grant revokes the Account Token and all Sessions
using it. Auth0 browser sign-ins are a separate source: ordinary MCP OAuth has no Poppy Session, and a Poppy agent's
browser cookie does not become the person's Auth0 cookie. See [session controls](/architecture/request-flows/account-api#sign-out-everywhere)
and [logout propagation](/architecture/request-flows/back-channel-logout) for enforcement and timing limits.

## WebMCP and payments

WebMCP exposes tools to an assistant inside the browser being used. Poppy identifies an external Personal Agent.
The webshop supports both: WebMCP tools act as the current browser visitor, including that visitor's Poppy
permissions when the browser belongs to an agent.

A person adds a saved card through Stripe Elements. Browser checkout can complete a bank challenge; an agent
uses the saved card off-session under `checkout` and cannot complete that challenge. Payments that need it fail
with `payment_requires_action`. Charge and refund retries use payment idempotency keys; checkout requests do not
have a general idempotency-key contract.

## Implementation references

- [Getting started](/getting-started): run the local shop and prepare your own deployment.
- [System map](/architecture) and [components](/architecture/components): who owns each capability.
- [Poppy request flows](/architecture/request-flows/poppy-agents): token verification, browser forwarding, authority and conversations.
- [Poppy compliance](/architecture/poppy-compliance): protocol requirements, implementation limitations and tests.
- [Invited agents](/architecture/auth0/invited-agents): independent agent identities and delegated browser sessions.
- [MCP clients](/mcp): standard OAuth and Session-backed access to the canonical MCP resource.