# auth.md

Agent authentication and access notes for **Philter Labs** (https://shopphilter.com).

## Audience

AI agents, shopping assistants, and automation that need **public catalog** data or to deep-link humans into the storefront.

## Public (no registration)

Most discovery surfaces need **no** agent credentials:

| Resource | URL |
|---|---|
| Brand summary | https://shopphilter.com/llms.txt |
| Full context | https://shopphilter.com/llms-full.txt |
| Markdown pages | Request any public HTML URL with `Accept: text/markdown` |
| OpenAPI | https://shopphilter.com/openapi.json |
| API catalog | https://shopphilter.com/.well-known/api-catalog |
| Agent skills | https://shopphilter.com/.well-known/agent-skills/index.json |
| MCP card | https://shopphilter.com/.well-known/mcp/server-card.json |
| MCP tools | `POST https://shopphilter.com/api/mcp` (JSON-RPC) |

## Store API (catalog / cart)

Commerce data is served by **Medusa Store API**:

- **Base:** `https://api.shopphilter.com/store`
- **Docs:** https://docs.medusajs.com/api/store
- **Auth:** Publishable API key header `x-publishable-api-key` (storefront builds embed a public publishable key; treat as non-secret site identifier, not a user credential).
- **Human accounts:** Email/password (and session cookies) on https://shopphilter.com/account — **not** OAuth/OIDC for third-party agents yet.

## Agent registration (OAuth 2.0)

Agents can self-register for an API identity — open dynamic client registration (RFC 7591), `client_credentials` grant only, scoped to `catalog:read`:

1. **Register:** `POST https://api.shopphilter.com/oauth/register` with optional `{"client_name": "..."}` — returns `client_id` + `client_secret`.
2. **Token:** `POST https://api.shopphilter.com/oauth/token` with `{"grant_type": "client_credentials", "client_id": "...", "client_secret": "..."}` — returns a 1-hour ES256 JWT.
3. **Use:** send `Authorization: Bearer <token>` to agent surfaces (e.g. `POST https://shopphilter.com/api/mcp`). Tokens identify your agent; anonymous access to the same public data remains allowed.

Discovery documents:

- `https://shopphilter.com/.well-known/oauth-authorization-server` (RFC 8414, includes the `agent_auth` block)
- `https://shopphilter.com/.well-known/oauth-protected-resource` (RFC 9728)
- JWKS: `https://api.shopphilter.com/oauth/jwks`

Scope boundary: `catalog:read` tokens grant **no** customer, order, cart, payment, or admin access — they identify the calling agent on public-catalog surfaces. There are no user-interactive grants (no authorization endpoint) and no OpenID Connect identity layer (`/.well-known/openid-configuration` is intentionally absent — nothing here authenticates humans).

To integrate as a partner beyond catalog access (wholesale, affiliate, custom integrations):

1. Contact humans via https://shopphilter.com/pages/contact or https://shopphilter.com/wholesale
2. Affiliates: https://shopphilter.com/affiliates

## Payments

Agent-native payment protocols (x402, MPP) are **not** enabled. Complete purchase by directing the user to product pages and checkout on https://shopphilter.com.

## Identity claims

No agent identity assertion (ID-JAG) or verified-email claim endpoints are offered.

## Security boundaries

Agent surfaces on this origin are **read-only public marketing/catalog** data:

- No access to customer accounts, orders, carts, or admin
- MCP tools cannot place orders or take payment
- Publishable API keys are public site identifiers (same as storefront JS), not staff secrets
- Do not send passwords, payment cards, or PII to agent discovery endpoints