What Is poppy.json? A Personal Agent Protocol Example, and How to Validate Yours

The Personal Agent Protocol (PAP, nicknamed Poppy) is a new open protocol, led by Sierra and Meta, for how a person's AI agent works with a company on their behalf: signing in as the user, using the company's APIs, joining a website session, or talking to the company's own agent. Draft 0.1 was published on 9 October 2026, with 35 design partners including OpenAI, Visa, Mastercard and PayPal.

Everything a personal agent does with a company starts by reading one file: /.well-known/poppy.json. This post explains what that file is, shows a complete example, and covers the checks an agent makes before trusting it.

Not to be confused with the poppy.json used by the Poppy robotics project (pypot). This one is the Personal Agent Protocol's discovery document.

Where poppy.json lives

At https://{your-domain}/.well-known/poppy.json, served over HTTPS as JSON. It may redirect (for example to a provider that hosts it), but every redirect must stay on HTTPS, and the document still speaks for the domain the agent asked for.

A poppy.json example

{
  "protocol_version": "0.1",
  "organization": { "name": "Example Company", "domain": "example.com" },
  "auth": {
    "issuer": "https://auth.example.com",
    "direct": { "scopes": ["poppy:read", "poppy:write", "addresses"] },
    "device": { "scopes": ["poppy:read", "poppy:write"] },
    "custom_scopes": { "addresses": "Manage saved shipping addresses" }
  },
  "agent": {
    "protocols": [{ "type": "poppy", "endpoint": "https://api.example.com/poppy/conversations" }]
  },
  "web": { "browser_session_endpoint": "https://example.com/poppy/browser-session" },
  "apis": [
    { "type": "openapi", "url": "https://api.example.com/openapi.json", "description": "Orders, returns, and exchanges" },
    { "type": "mcp", "url": "https://mcp.example.com/mcp", "description": "Product search and sizing" }
  ]
}

This is shortened from the example in the specification. A field-by-field version is on the What is poppy.json? guide.

What each field means

Field	Required	What it says
protocol_version	Yes	The version the document follows, as major.minor. Draft 0.1 is "0.1". Agents must not use a document whose major version they don't support.
organization	Yes	Display name and domain. The domain must match the host the agent requested (ignoring a leading www.).
auth	When agent, apis or a browser session is listed	The OAuth issuer and the sign-in types the company supports (direct, device, mediated), each with the scopes it can grant. custom_scopes describes anything beyond poppy:read and poppy:write.
agent	One of agent, apis, web	The company's own agent: its conversation protocols, each with a type and an HTTPS endpoint.
apis	One of agent, apis, web	APIs the agent can call, each with a type (openapi or mcp), a url and a short description.
web	One of agent, apis, web	The website. The optional browser_session_endpoint lets the agent's browser join its session, so pages apply the user's sign-in.
extensions	No	Extensions the company supports, keyed by name, each with a version. operations is defined with the protocol; anyone else's start with a domain, such as example.com/gift-wrap.

The check agents make on your sign-in server

A valid-looking poppy.json isn't enough. Before using it, a personal agent fetches the OAuth server metadata of auth.issuer (RFC 8414, at /.well-known/oauth-authorization-server) and checks two things:

1. Its issuer matches auth.issuer exactly.
2. Its poppy_domains lists your domain. This field isn't part of the OAuth standard; PAP adds it to the metadata so the sign-in server can say which domains it works for.

Without that second check, a fake site could publish a poppy.json naming your real sign-in server, and agents would send users there. The metadata must also publish a token_endpoint and revocation_endpoint, plus authorization_endpoint for direct sign-in and device_authorization_endpoint for device sign-in.

Common poppy.json mistakes

• organization.domain set to a parent brand or a different country domain. Several domains can share one issuer, but each names itself and each must appear in poppy_domains.
• Custom scopes that start with poppy:. That prefix is reserved; only poppy:read and poppy:write are allowed.
• An MCP server whose resource metadata doesn't list your issuer in authorization_servers, so MCP clients can't sign in.
• A storefront that answers every path with its HTML page. Agents need JSON at the well-known URL, not a soft 404.

Who publishes poppy.json today?

Almost nobody, yet. On 11 October we checked the launch partners and design partners, including Shopify, Stripe, Walmart, Meta, Visa, Mastercard, PayPal, OpenAI and Cloudflare. None serve /.well-known/poppy.json so far. The only live files are developer demos. That's expected three days after a draft. It also means the first company to publish a correct file will be easy to spot.

The running list, with the day each domain was first seen, is at papchecker.com/sites.

How to validate your poppy.json

I built PAP Checker to check a domain against draft 0.1 from the outside, the same way a personal agent would. Enter a domain and it:

• fetches /.well-known/poppy.json and follows redirects, as an agent would;
• checks discovery (protocol_version, organization, the domain match);
• fetches the issuer's OAuth metadata and checks sign-in (issuer match, poppy_domains, the required endpoints for each sign-in type);
• checks scopes, routes (agent, APIs, website, all on HTTPS) and extensions;
• ties every result to the section of the specification it comes from.

It only reads public documents. It never signs in, starts a session, or calls your APIs. It's free and needs no sign-up.

👉 Check your poppy.json at papchecker.com

Caveats

Draft 0.1 can still change in ways that break existing files, and Sierra has said a reference implementation is coming. The checker follows the published draft and will move with it. If you find a rule it gets wrong, tell me in the comments.

Disclosure: I maintain PAP Checker and UCP Checker, which does the same job for the Universal Commerce Protocol. PAP Checker isn't affiliated with the protocol's authors.