# Agent Access — Zeruvmed Storefront

This document describes how AI agents authenticate and act on
[Zeruvmed](https://zeruvmed.com), the premium healthcare apparel storefront.

## What's open without auth

The catalog and guest checkout are **public** — no token required:

- `GET /api/v1/products` — search products (`search_products`)
- `GET /api/v1/products/{slug}` — product detail (`get_product`)
- `GET /api/v1/categories` — list categories (`list_categories`)
- `POST /api/v1/orders/guest` — place a guest order (`create_order`)

Machine-readable description: [`/openapi.json`](https://zeruvmed.com/openapi.json).

## What needs a token

Customer-scoped reads require an OAuth 2.0 bearer token:

- `GET /api/v1/orders/me` — order history (`check_order_status`), scope `orders.read`

## OAuth metadata

> **Status: preview.** The catalog and guest-order tools above are live
> today. The interactive OAuth flow below is being rolled out — the
> metadata endpoints are published so agents can discover the canonical
> paths ahead of GA.

- Authorization Server Metadata (RFC 8414): [`/.well-known/oauth-authorization-server`](https://zeruvmed.com/.well-known/oauth-authorization-server)
- OpenID Configuration: [`/.well-known/openid-configuration`](https://zeruvmed.com/.well-known/openid-configuration)
- Protected Resource Metadata (RFC 9728): [`/.well-known/oauth-protected-resource`](https://zeruvmed.com/.well-known/oauth-protected-resource)

### Registering a client

1. Discover endpoints from the Authorization Server Metadata above.
2. Register via the `registration_endpoint` (dynamic client registration).
3. Run the authorization-code + PKCE (`S256`) flow, or
   `client_credentials` for server-to-server access.
4. Request the narrowest scope you need: `products.read`, `orders.read`,
   or `orders.write`.

## Other discovery surfaces

- MCP server card (SEP-1649): [`/.well-known/mcp/server-card.json`](https://zeruvmed.com/.well-known/mcp/server-card.json)
- Agent Skills index: [`/.well-known/agent-skills/index.json`](https://zeruvmed.com/.well-known/agent-skills/index.json)
- API catalog (RFC 9727): [`/.well-known/api-catalog`](https://zeruvmed.com/.well-known/api-catalog)
- LLM site index: [`/llms.txt`](https://zeruvmed.com/llms.txt)

Browsers visiting any public page also receive in-page tools via
[WebMCP](https://github.com/webmachinelearning/webmcp)
(`navigator.modelContext`), exposing the same five tools listed above.