> ## Documentation Index
> Fetch the complete documentation index at: https://docs.populardemand.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> OAuth, and the permissions the buyer grants.

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](https://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.

| Scope | Effect | Tools |
| - | - | - |
| `purchases:read` | none | `list_requests`, `get_request`, `get_offers` |
| `purchases:write` | reversible | `save_request`, `update_request`, `answer_question`, `respond_to_offer`, `set_notifications` |
| `purchases:irreversible` | irreversible | `close_request` |

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.

## Permissions (consent)

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.

| Permission | Lets your agent |
| - | - |
| `read` | Read Requests, Offers and questions. Always included. |
| `create` | Save new Requests. |
| `update` | Change Requests and add models. |
| `close` | Close Requests. The buyer can reopen them for 7 days. |
| `offer_fit` | Say whether an Offer fits what the buyer asked for (`respond_to_offer`). |
| `reaffirm` | Confirm the buyer still wants something (`still_want`), check Offers for them and confirm deliveries. Left out by default. The buyer grants it separately. |
| `research` | Add the prices it finds to a Request. |
| `reachability` | Choose how the buyer and your agent are reached about a Request. |

`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](https://populardemand.market/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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.