# auth.md — Qyvora agent access

Audience: autonomous agents, LLM assistants, and integration tools that read the Qyvora perfume storefront programmatically.

## Overview

Most Qyvora storefront APIs are **public read** endpoints protected by IP rate limiting (60 requests/minute per IP). They do **not** require OAuth bearer tokens.

Customer-specific actions (account, checkout, signed-in assistant hints) use **Supabase Auth** browser sessions established via `/login`.

## Anonymous access {#anonymous-access}

Public endpoints you can call without registration:

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/api/health` | GET | Liveness |
| `/api/catalog/reels` | GET | Product reel metadata |
| `/api/reviews` | GET | Approved reviews |
| `/api/shipping/offices?carrier=econt` | GET | Courier offices |
| `/api/assistant/voice-status` | GET | Voice feature flags |
| `/llms.txt` | GET | Site guide (markdown) |
| `/llms-full.txt` | GET | Full product catalog (markdown) |
| `/.well-known/api-catalog` | GET | RFC 9727 API catalog |
| `/.well-known/openapi.json` | GET | OpenAPI 3.1 spec (catalog + assistant) |
| `/openapi.json` | GET | MPP agent commerce OpenAPI (`x-payment-info`) |
| `/.well-known/acp.json` | GET | Agentic Commerce Protocol discovery |
| `/.well-known/ucp` | GET | Universal Commerce Protocol profile |

Send `Accept: text/markdown` on HTML pages (e.g. `/`, `/help`, `/shop/{slug}`) to receive markdown instead of HTML.

**Credential type:** `none` — no API key or bearer token is required for the endpoints above.

## Agent commerce (MPP + ACP + UCP)

Machine-readable commerce discovery for autonomous buyers:

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `POST /api/agent/commerce/checkout_sessions` | POST | Create Stripe checkout session after MPP payment (402 → pay → retry) |
| `/openapi.json` | GET | Payable operations with `x-payment-info` (Stripe via MPP) |
| `/.well-known/acp.json` | GET | ACP protocol version, `api_base_url`, capabilities |
| `/.well-known/ucp` | GET | UCP shopping checkout profile + payment handlers |

Request body for `checkout_sessions`: `line_items` (product slug, quantity, optional volume), `buyer` (name, email, phone), `shipping` (courier office or address). Returns `402` with MPP challenge until payment credential is supplied.

Human browser checkout remains at [`/checkout`](https://qyvora.store/checkout) — do not automate without user consent.

## Agent registration

Machine-readable registration metadata is published in the `agent_auth` block at [`/.well-known/oauth-authorization-server`](https://qyvora.store/.well-known/oauth-authorization-server):

- **Register URI:** `https://qyvora.store/auth.md` (this document)
- **Identity types:** `anonymous`
- **Credential types:** `none`
- **Claim URI:** `https://qyvora.store/auth.md#anonymous-access`

No separate agent signup endpoint is required. Do not automate `/login` without explicit user consent.

## OAuth Protected Resource Metadata

Machine-readable resource metadata: [`/.well-known/oauth-protected-resource`](https://qyvora.store/.well-known/oauth-protected-resource)

- **Resource identifier:** `https://qyvora.store`
- **Authorization server (issuer):** `https://qyvora.store`
- **Authorization server metadata:** [`/.well-known/oauth-authorization-server`](https://qyvora.store/.well-known/oauth-authorization-server)
- **Scopes:** `catalog:read`, `assistant:chat`, `reviews:read`

## Customer session (optional)

For signed-in customer context:

1. Direct humans to [`/login`](https://qyvora.store/login) (Supabase Auth).
2. Session cookies (`sb-*`) are set on the storefront origin after sign-in.
3. `GET /api/assistant/customer-hint` returns a signed-in customer snapshot when the session cookie is present.

Agents should **not** automate login without explicit user consent.

## Assistant (Alfret)

- UI: [`/help`](https://qyvora.store/help)
- Chat API: `POST /api/assistant/chat` (JSON body with `messages` array; may stream)
- Recommendations: `POST /api/assistant/perfume-suggest`
- Order lookup: `POST /api/assistant/order-lookup` (order number or tracking ID)

Respect rate limits. Do not scrape checkout or account pages.

## Related discovery

- API catalog: [`/.well-known/api-catalog`](https://qyvora.store/.well-known/api-catalog)
- Agent commerce OpenAPI (MPP): [`/openapi.json`](https://qyvora.store/openapi.json)
- ACP discovery: [`/.well-known/acp.json`](https://qyvora.store/.well-known/acp.json)
- UCP profile: [`/.well-known/ucp`](https://qyvora.store/.well-known/ucp)
- Agent skills index: [`/.well-known/agent-skills/index.json`](https://qyvora.store/.well-known/agent-skills/index.json)
- MCP server card: [`/.well-known/mcp/server-card.json`](https://qyvora.store/.well-known/mcp/server-card.json)