# auth.md for Horeca

Horeca supports OAuth 2.1 authorization code with PKCE for agent clients that use the Horeca MCP server. Account sign-in uses a verified email address and password; passwords must contain at least 12 characters. Users approve each client in Horeca before it receives an access token.

## Discover and register

1. Read the protected resource metadata at <https://horeca.derrumbar.top/.well-known/oauth-protected-resource>.
2. Read the authorization server metadata at <https://horeca.derrumbar.top/.well-known/oauth-authorization-server>. It lists the authorization, token, registration, and revocation endpoints.
3. Prefer Client ID Metadata Documents (CIMD), with a public HTTPS metadata URL as `client_id`. Dynamic Client Registration is also available at <https://horeca.derrumbar.top/api/auth/oauth2/register> for clients that do not support CIMD.
4. Start an authorization code flow using PKCE and the protected resource identifier `https://horeca.derrumbar.top/api/mcp`.
5. Request `horeca:catalog:read` to use the catalog search tool. `openid` identifies the signed-in Horeca account; `offline_access` permits refresh tokens when requested.
6. Send the issued access token as a bearer token to `POST https://horeca.derrumbar.top/api/mcp`.

The consent screen names the client and requested scopes. Catalog access is available only to buyer accounts. The token is audience-bound to the MCP endpoint and is not accepted by other `/api/` routes.

## Available agent tools

The authenticated MCP server exposes the read-only `search_catalog` tool. It returns matching products and current offers visible to the buyer account. It cannot create quotes, place orders, update supplier data, or start payments.

When the Horeca application is open in a supported browser, WebMCP also exposes `search_catalog` and `add_to_cart`. Adding a product changes the signed-in buyer’s browser cart only; it does not place an order or start a payment.

## Revoke access

OAuth clients can revoke their token at the revocation endpoint advertised in authorization server metadata (currently <https://horeca.derrumbar.top/api/auth/oauth2/revoke>). Horeca uses the standard OAuth revocation flow; the application does not implement the separate WorkOS ID-JAG identity assertion or claim-code protocol.

The public health endpoint is <https://horeca.derrumbar.top/api/healthz>. See [API documentation](https://horeca.derrumbar.top/api.md) and the [API catalog](https://horeca.derrumbar.top/.well-known/api-catalog).