# auth.md — how agents authenticate to Catalog

You are an agent. This service supports **agentic registration**: discover → register → exchange for an access_token → call the API → handle expiry. Follow the steps in order. Almost everything on getcatalog.ai is public — the markdown mirror (`Accept: text/markdown`), `/llms.txt`, `/blog.json`, the audit request API, and every tool on the MCP server at https://www.getcatalog.ai/mcp work without credentials — so read this when you want an identity Catalog can recognise, or when a response arrives with `WWW-Authenticate`.

Roles:

- **Resource server**: https://www.getcatalog.ai — the MCP endpoint is the protected resource.
- **Authorization server**: https://www.getcatalog.ai (metadata below). Registration and the jwt-bearer exchange are handled here; the user-login endpoints are hosted by Clerk at https://clerk.getcatalog.ai, the identity provider Catalog's merchant app signs in with, which is the issuer of every user token.

## Step 1 — Discover

Fetch the Protected Resource Metadata (RFC 9728) at <https://www.getcatalog.ai/.well-known/oauth-protected-resource> (the site) or <https://www.getcatalog.ai/.well-known/oauth-protected-resource/mcp> (the MCP endpoint — the path-inserted location MCP clients try first, and what a 401's `resource_metadata` names). Its `authorization_servers` lists this site first and Clerk second. This site's metadata (RFC 8414 / OpenID Discovery) is at <https://www.getcatalog.ai/.well-known/oauth-authorization-server>; its `agent_auth` block is the bootstrap surface for this profile.

Fields that matter:

- `resource` — the audience you are authenticating for.
- `token_endpoint` — where identity assertions are exchanged (Step 3) and where Clerk's authorization_code / refresh_token grants are accepted (they pass through to Clerk).
- `grant_types_supported` — includes `urn:ietf:params:oauth:grant-type:jwt-bearer` when registration is enabled.
- `agent_auth.identity_endpoint` / `agent_auth.identity_types_supported` — where and how to register (Step 2). Empty means registration is off on this deployment.
- `agent_auth.token_issuer` — Clerk: the `iss` in ID tokens and the party that mints user tokens. Service-issued agent tokens carry `iss` = this site.
- `agent_auth.authorization_required: false` — no token is needed for the public tools. Skip to Step 4 if you do not need an identity.

## Step 2 — Register

Anonymous registration is **not enabled on this deployment** (`agent_auth.identity_types_supported` is empty and the identity endpoint is not advertised). Skip to Step 3b to act as a Catalog user, or use the public tools without a token.

## Step 3 — Exchange the assertion

Not applicable while registration is disabled.

## Step 3b — Alternative: act as a Catalog user

Standard OAuth 2.1 authorization code + PKCE (`S256`) against the `authorization_endpoint` in the metadata, then exchange the code at https://www.getcatalog.ai/oauth2/token (it passes through to Clerk). Dynamic client registration is not enabled: email hamish@getcatalog.ai with the agent's name, redirect URI(s), and the merchant it acts for to get a client id. Public clients (`token_endpoint_auth_methods_supported` includes `none`) must use PKCE. Request `openid email profile`; add `offline_access` for a refresh token. Before you start, tell the user which Catalog account you are about to act as.

## Step 4 — Use

Send the access token as a bearer header on MCP requests. The server verifies it and the `whoami` tool returns the identity it resolved to (`agent:reg_…` for registered agents, the Clerk subject for users):

```http
POST https://www.getcatalog.ai/mcp
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}
```

An invalid or expired token gets `401` with a `WWW-Authenticate: Bearer` challenge whose `resource_metadata` is the MCP document from Step 1; re-register or refresh. Requests without a token are never rejected for lack of one.

## Step 5 — Expiry and revocation

- Service-issued agent tokens live one hour and are not revocable (nothing is stored); register again for a fresh one.
- Clerk user tokens: refresh with `grant_type=refresh_token` at https://www.getcatalog.ai/oauth2/token; revoke (RFC 7009) at https://clerk.getcatalog.ai/oauth/token/revoke with `token=<token>` when the user ends the session.

## Consent rules

- Tell the user which Catalog account you are about to act as before Step 3b.
- `request_product_audit` (MCP) and `POST /api/audit-request` share the requester's name, email, and brand site with the Catalog team. Call them only after the user has explicitly agreed to that.

Site guide: https://www.getcatalog.ai/llms.txt · Skills: https://www.getcatalog.ai/.well-known/agent-skills/index.json · API catalog: https://www.getcatalog.ai/.well-known/api-catalog
