# Popular Demand authentication for agents Public pages, https://populardemand.site/llms.txt, https://populardemand.site/developers and https://populardemand.site/api/openapi need no credentials. Everything private belongs to a person, who decides what an agent may do and can take it back. OAuth scopes only identify the person. What an agent may do (read, save, reaffirm, pay-link) is a separate grant the person approves on the consent page, and it can be revoked. ## Discover - Protected-resource metadata (RFC 9728) for the buyer MCP server and the owner REST API: https://populardemand.site/.well-known/oauth-protected-resource, also at https://populardemand.site/.well-known/oauth-protected-resource/mcp. Seller MCP server: https://populardemand.site/.well-known/oauth-protected-resource/seller/mcp. - An unauthenticated call (any HTTP method) to https://populardemand.site/mcp or https://populardemand.site/seller/mcp, or to the owner REST API under https://populardemand.site/api/purchases, answers 401 with `WWW-Authenticate: Bearer resource_metadata="..."` naming that resource's metadata. - Authorization server: https://utwxldenhpdtejhuuehx.supabase.co/auth/v1. Its RFC 8414 metadata, at https://utwxldenhpdtejhuuehx.supabase.co/.well-known/oauth-authorization-server/auth/v1, lists the authorization, token and registration endpoints and PKCE `S256`; https://populardemand.site/.well-known/oauth-authorization-server and https://populardemand.site/.well-known/openid-configuration redirect to its metadata. ## Pick a method 1. **No account, one draft.** For saving a single Request on the person's behalf before they have an account. See Register, then Claim. 2. **OAuth for the buyer MCP server and owner REST API.** For an agent that keeps a person's Requests current and reads their Offers. Resource: https://populardemand.site/mcp; the same token works under https://populardemand.site/api/purchases. 3. **OAuth for the seller MCP server.** For an agent working for a seller. Resource: https://populardemand.site/seller/mcp. 4. **Email delegation.** A verified person approves one exact agent mailbox. Details and the EmailCommand schema: https://populardemand.site/for-agents#email and https://populardemand.site/api/openapi. One OAuth client is either a buyer agent or a seller agent for a person, never both. A buyer agent's client has no seller grant, so the seller server refuses it. ## Register - **No account:** POST https://populardemand.site/api/purchases/drafts with a fresh random `Idempotency-Key` of 32 to 128 characters and the PurchaseInput body from the OpenAPI description. The 201 response (`DraftReceipt`) holds `capability_token` (private), `activation_url` (for the person), `status_url`, `draft_id` and `expires_at`. The activation link expires sooner, at `activation_expires_at` (20 minutes); if it lapses before the person uses it, get a fresh one with POST https://populardemand.site/api/purchases/{draft_id}/activation-link and the capability token. `expires_at` is when the draft itself ends. - **OAuth:** your `client_id` comes from registering your agent with the authorization server; most MCP hosts do this for you when the person adds the server. To register yourself, POST an RFC 7591 registration to the `registration_endpoint` in its RFC 8414 metadata with a `client_name` and your `redirect_uris`; the response holds your `client_id`. A client without a secret uses `token_endpoint_auth_method` `none` with PKCE. There is no manual sign-up and no pre-issued `client_id`, and Client ID Metadata Documents are not supported. - **Keep your `client_id`.** The person approves a grant for that exact `client_id`. Registering again creates a new client, which they must approve again and which their account lists as a separate agent. - The consent page shows the person your `client_name`, marked as given by the app itself, and the host of your redirect URI. Use a name they will recognise. - **No browser on the agent's computer:** the command-line client (https://populardemand.site/developers#cli) registers `https://populardemand.site/cli/signed-in` as its redirect URI. After the person approves, that page shows them one code starting with `pdc_`, carrying the authorization code and `state`; they give it to the agent, which checks the `state` and exchanges the code with its own PKCE verifier. ## Claim A credential does nothing until the person claims it. - **Draft:** give the person the activation link. They verify their email and confirm the Request; until then it is saved but is not active demand. - **Buyer OAuth:** after sign-in, the person approves a grant for your client on the consent page, choosing permissions from: read, create, update, close, reaffirm, research, reachability. Read is always included. Default approval leaves out reaffirm, which the person can grant separately; reaffirm is also what lets an agent start a payment hold, which the person still authorizes themselves at checkout. - **Seller OAuth:** an owner or admin at the seller approves your client as a seller agent for their company, with permissions read, draft and request_approval. Agents draft Quotes and ask for approval; only a signed-in person at the seller submits a binding Quote. - **Email:** the agent reads the private challenge sent to its approved mailbox and binds before sending commands. A sender address or thread never grants authority. ## Exchange Use the authorization code flow with PKCE (S256) and `resource=https://populardemand.site/mcp` (or the seller resource) at the authorization server's authorization and token endpoints. Access tokens are short-lived: read `expires_in` from the token response, and renew with the `refresh_token` grant, sending the same `resource`. If refreshing fails, ask the person to connect again. Token scopes are `openid` and `email`. Until the authorization server issues per-resource audiences, tokens carry the Popular Demand buyer audience, which the seller server also accepts; the seller grant is what authorizes there. ## Use the access_token - OAuth: `Authorization: Bearer ` on every MCP and REST call. Each tool and route checks the grant's permissions for that call. - Draft capability: `Authorization: CondiCapability `. It reads only that one Request and carries it through activation. Keep it private and never put it in a URL. - Writes need an `Idempotency-Key` (REST) or `request_key` (MCP); repeat it to retry the same command safely. - No API or MCP tool authorizes payment by itself. ## Errors Errors are JSON: `{"error":{"code":"...","message":"...","hint":"..."}}`, where `hint` (when present) names the next step. A missing or invalid token answers 401 (`unauthenticated`) with the `WWW-Authenticate` challenge; a revoked grant answers 401 (`grant_revoked`); a missing permission answers 403 (`forbidden`); too many calls answer 429 (`rate_limited`) with `Retry-After`. All codes: https://populardemand.site/developers#errors. ## Revocation - The person can revoke an agent's grant at any time in their account (https://populardemand.site/account); later calls then fail with `grant_revoked` or `unauthenticated`. Stop, and ask them to reconnect if they want to. - Read-only status access to a Request can be revoked by the person on that Request's page. A draft capability ends when its draft expires. - An approved email mailbox can be revoked in the account, and expires on the date the person chose. - Agents have no endpoint to revoke a person's grant themselves; ask the person. More: https://populardemand.site/developers, https://populardemand.site/for-agents