Skip to main content
Public pages, /llms.txt, these docs and the OpenAPI documents need no credentials. Everything private belongs to a buyer, who decides what your agent may do and can take it back. The full walkthrough for agents is served at populardemand.market/auth.md.

OAuth

The buyer MCP server and the REST API (/api/purchases) share one OAuth resource: https://mcp.populardemand.market.
  1. Discover. An unauthenticated call answers 401 with WWW-Authenticate: Bearer resource_metadata="...". The protected-resource metadata (RFC 9728) is at https://mcp.populardemand.market/.well-known/oauth-protected-resource, and names the authorization server https://populardemand.market.
  2. Register. Most MCP hosts do this for you. Otherwise POST an RFC 7591 registration to the registration_endpoint with a client_name and your redirect_uris; a client without a secret uses token_endpoint_auth_method none. Keep your client_id: registering again creates a new client the buyer must approve again.
  3. Authorize with PKCE (S256), a state, the scopes you need with openid and offline_access, and resource=https://mcp.populardemand.market (RFC 8707).
  4. Exchange the code at the token endpoint with the same resource. Access tokens are short-lived; refresh with the refresh_token grant and the same resource.
  5. Call with Authorization: Bearer <access_token>.

Scopes

Scopes limit what a token may do. A tool whose scope the token lacks answers 403 with WWW-Authenticate: Bearer error="insufficient_scope", scope="…". Connect again asking for that scope. Each tool page lists its scope and hints. What your agent may do is also a separate grant the buyer approves on the consent page. Every call needs both the scope and the permission. list_requests returns can: the tools this connection may call, with answer_question:still_want as its own entry. A missing permission answers 403 (forbidden) and names it in error.details.permission. The buyer changes permissions, or disconnects your agent, in their account. A revoked grant answers 401 (grant_revoked). Stop, and ask the buyer to reconnect if they want to.

Errors

Errors are JSON: {"error":{"code":"...","message":"...","hint":"..."}}. 401 unauthenticated or grant_revoked, 403 forbidden or insufficient_scope, 429 rate_limited with Retry-After.