Working with a store that runs Agent Adapt

For a worked path through the signed-out flow, with every field in every request, see An agent’s first visit, request by request.

Discovery

Everything starts at the store’s domain:

GET https://store.example/.well-known/poppy.json

Your agent’s identity

Your client_id is the HTTPS URL of your client metadata document, as the specification requires. The store fetches it and your jwks_uri, caches both, and refetches the keys once when it sees a new kid.

• token_endpoint_auth_method must be private_key_jwt.
• jwks_uri and every redirect_uris entry must be HTTPS on your client_id’s domain or a subdomain.
• Signing algorithms: ES256 and RS256 (RSA keys of 2048 bits or more). none and HMAC are refused.
• Client assertions live at most 300 seconds, and each jti is accepted once.
• List extensions in your metadata to receive them; the store never sends operations to an agent that doesn’t.

Sessions and tokens

Signing a customer in

• Direct Sign-In: /agent-adapt/oauth/authorize with PKCE (S256 only), your registered redirect_uri, and session_id at the code exchange. Responses carry iss (RFC 9207).
• Device Sign-In: /agent-adapt/oauth/device; the customer enters the code at /agent-adapt/device.
• Scopes: poppy:read and poppy:write; with Pro, addresses, described in auth.custom_scopes. The customer can approve fewer than you ask for, so read scope in the response.
• Administrator and shop manager accounts are refused at sign-in and on every request after it.

The API

Every call goes to /wp-json/agent-adapt/v1 with Authorization: DPoP and a fresh proof. The OpenAPI description is public and generated from the same registry the routes come from, so it can’t drift.

• Errors are {"error", "error_description"}, with WWW-Authenticate: DPoP for invalid_token, sign_in_required and insufficient_scope.
• Over the limit: HTTP 429 with Retry-After.
• GET responses carry an ETag and answer If-None-Match with 304, so checking a cart or a product for changes is cheap.
• Another customer’s order and a missing one get the same 404.

Checkout

Draft 0.1 leaves payments as an open topic, so agents don’t pay. POST /cart/handoff returns a single-use link, valid for 30 minutes. The customer opens it in their own browser, the cart moves into their session, and they check out on the store. The order records your agent in WooCommerce’s order attribution.

Your agent’s browser

Post a poppy-browser+jwt assertion to the browser session endpoint as a form, never in the URL. It may live at most 60 seconds, and return_to must be on the store’s domain. The browser then shares the Session’s cart and sign-in. It is refused the dashboard, the login page, account details, payment methods and checkout.

Operations Pro

Write actions that change an order or an account are proposed as operations (extension v1) for agents that list the extension. Agents that don’t list it get extension_required, or the plain action where the free plugin offers one.

• Proposals answer 202 with {"operation": …}; the OpenAPI description marks those endpoints.
• Confirm at /wp-json/agent-adapt/v1/operations/{id}/confirm with revision and approved_by. Only the latest revision can be confirmed (terms_changed, 409).
• Refunds and address changes need user_approval_required: a standing permission is refused.
• Confirming is at-most-once across retries and concurrent requests. An outcome the store can’t confirm stays in_progress, with Retry-After.

MCP Pro

• Streamable HTTP at /agent-adapt/mcp: MCP 2026-07-28 (stateless), and initialize-based 2025-11-25 and 2025-06-18.
• Protected resource metadata (RFC 9728) at /.well-known/oauth-protected-resource/agent-adapt/mcp; its authorization server is the store’s issuer.
• A Personal Agent gets a Bearer token by asking the token endpoint without a DPoP proof, with resource set to the MCP URL. That token works at the MCP server and nowhere else.
• A stock MCP client signs in through MCP’s own flow with a Client ID Metadata Document (token_endpoint_auth_method: none), PKCE and resource. Loopback redirects match on any port.
• Tools are the API’s capabilities, named like catalog_search, under the same scopes and policy. Operations come back in structuredContent.operation and are confirmed at the operations endpoint.