# Auth.md — Molino & Cata Agent API authentication

Molino & Cata exposes two agent surfaces with different trust boundaries:

- **Public, anonymous (no credential).** The read-only catalog REST API
  (`https://molinoycata.com/api/v1/public`) and the customer MCP server (`https://molinoycata.com/mcp`)
  serve already-public catalog data and require **no authentication**. Just
  call them. They are rate-limited at the edge.
- **Operator Agent API (manual bearer token).** `https://molinoycata.com/api/v1/agent`
  and the operator MCP (`https://prensa.molinoycata.com/mcp`) expose
  business operations and are protected with **manually issued** bearer
  tokens, scoped to least privilege.

## Discover

- OpenAPI: https://molinoycata.com/api/v1/openapi.json
- API Catalog: https://molinoycata.com/.well-known/api-catalog
- OAuth protected resource metadata: https://molinoycata.com/.well-known/oauth-protected-resource
- OAuth authorization server metadata: https://molinoycata.com/.well-known/oauth-authorization-server
- MCP server card: https://molinoycata.com/.well-known/mcp/server-card.json

## Pick a method

- Reading public catalog, products, tastings or store info → **anonymous**,
  no credential. Use the public REST API or the customer MCP.
- Operating the business (inventory, orders, refunds, Shopify) → **bearer
  token** on the operator Agent API.

## Register

**Molino & Cata does not support agentic self-registration.** There is no
`register_uri`, `claim_uri` or `revocation_uri`, and no self-service token,
API-key or client-credentials flow. Operator tokens are **issued manually**:
contact Molino & Cata with the integration name, intended use, required
scopes, operator contact and expected traffic volume.

## Use credential

Send the operator token in the HTTP `Authorization` header:

```http
Authorization: Bearer <token>
```

A `401` from the operator Agent API includes a `WWW-Authenticate: Bearer`
challenge whose `resource_metadata` points at the OAuth protected-resource
document above. Supported scopes: agent:admin, agent:read, agent:write, financial:read, shopify:retry, inventory:write, pii:read.

## Revocation

Operator tokens can be revoked at any time by Molino & Cata administrators
from the back office; revoked or expired tokens return `401`. There is no
self-service revocation endpoint.

## Error codes

Errors are JSON `{ "error": "<code>", "message": "<human readable>" }`:

- `401 unauthorized` — missing or invalid bearer token (operator API).
- `403 forbidden` — token lacks the required scope.
- `404 not_found` — resource not found.
- `409 idempotency_conflict` — idempotency key reused with a different body.
- `429 rate_limited` — too many requests; honour `Retry-After`.