Personal Agent Protocol (Poppy)
The Personal Agent Protocol (Poppy) is an open protocol from Sierra. It tells a personal agent how to find a company's services, identify itself, and sign in for the person it works for. Descope delivers the company side of Poppy through Agent Login, so your site accepts Poppy agents without you building an authorization server.
Your setup depends on where your customers sign in today, so start with Which Setup Fits You.
What Poppy Asks of a Company
Poppy builds on standard OAuth. When a personal agent needs your user's account, it signs in with the authorization code flow or the device flow, and gets an access token and a refresh token. Descope runs that part as your authorization server.
Poppy adds a few rules on top. The agent identifies itself with Client ID Metadata Documents (CIMD) instead of registering. Your domain names the issuer in its protected resource metadata, and the issuer lists your domain in protected_resources, so a copied poppy.json on another domain doesn't work.
Sessions are the second layer, and they belong to the agent. On every request to your APIs, the agent signs a Poppy-Session header that names the agent, your user, and the Session. The header never reaches the authorization server, so your API verifies it wherever it keeps state across requests, such as a cart.
Which Setup Fits You
Every setup starts on the Agent Login page in the Console. What comes after depends on where your customers sign in today.
| Where your customers sign in today | What you set up | Where to go |
|---|---|---|
| Descope | Agent Login only. Agents connect to the user records you already have. | Already on Descope |
| Another provider or your own login | Agent Login, plus External Authentication to your login page | Connect your existing login |
| Nowhere, because your site has no accounts | Agent Login with email one-time codes | No login yet |
Already on Descope
Agent Login adds Poppy to the project you run today. Your customers approve agents with the sign-in methods they already use, and each agent connects to the customer's existing Descope user, so you have no accounts to link.
Select any step to see what happens.
Your APIs already trust the issuer, so they only need to check scopes as Developing APIs with OAuth describes. Use token introspection where sign-out has to take effect at once.
Another provider or your own login
Your customers keep signing in where they do today. Descope becomes the issuer that agents sign in to, and it sends your customers to your login page with External Authentication. Your APIs also need a way to accept Descope tokens, which Connect your existing login covers.
Select any step to see what happens.
Each customer who approves an agent becomes a Descope user. If you later move your customer login to Descope, those users are already in place, and your setup becomes the first row. See Migrating to Descope for that path.
No login yet
A site with guest checkout can offer Poppy without any authorization server, as long as agents only browse, search, or fill a cart. Agent Login comes in when agents need something tied to a customer, such as their orders.
Most stores already know their customers by the email on each order, so a verified email can serve as the account. Your customer approves the agent by confirming their email with a one-time password. Your API then validates the access token and matches its email claim to your records. Northbound, the Descope sample store, works this way.
Two choices are yours to make:
- An email with no record: Your backend can refuse the agent, or create a customer record so the agent can place a first order.
- What an email unlocks: An email match is only as strong as your records, so keep high-impact actions, such as refunds, behind a separate approval.
Each customer who approves an agent becomes a Descope user with a verified email. If you later add customer accounts, Descope can run that login too, and your setup becomes the first row.
Who Does What
Descope handles the OAuth side of Poppy. Your site keeps its accounts and its Sessions, and decides what an agent can do once it is signed in.
| Responsibility | Descope | Your company |
|---|---|---|
| Discovery files | Generates poppy.json and publishes your domains in protected_resources | Serves poppy.json and the protected resource metadata on your domain |
| Agent identity | Fetches each agent's client metadata and checks its signed requests | Approves which agents can connect |
| Sign-in | Runs authorization code and device sign-in and the consent screen | On another login, provides the login page through External Authentication |
| Your APIs | Publishes the keys and claims to check | Validates tokens, enforces scopes, and verifies the Poppy-Session header where it relies on it |
| Revocation | Revokes refresh tokens and the access tokens issued under them | Triggers revocation on events such as a password reset |
| Connected agents | Keeps an agentic identity for each agent and user | Shows the list in your account settings |
Agents can sign in as soon as you publish the files, but they have nothing to do until at least one API accepts their tokens. Plan for that API before you tell agents your site supports Poppy.
Next Steps
Start on the Agent Login page to create the issuer and the approval flow.
Agent Login
Set up a Poppy-compliant OAuth server so your customers' AI agents sign in, get the user's approval, and stay distinguishable from people.
Connect Your Existing Login
Let users approve Poppy agents with the account they already have on your site, using External Authentication, account linking, and consent.