# auth.md — Agent authentication for centrestagepermis.fr

You are an agent. This service supports **anonymous agentic registration**:
discover → register → get a token → call the API. Registration is optional —
every read endpoint also accepts unauthenticated requests — but authenticated
agents get a **higher rate-limit tier** keyed to their client, not their IP.

## Step 0 — What's here

- `GET /api/stages` — live course availability (JSON) — schema: /openapi.json
- `POST /api/mcp` — MCP JSON-RPC (search_stages, check_availability, get_centre,
  list_articles, get_article) — card: /.well-known/mcp/server-card.json
- `GET /llms.txt` — content manifest · `GET /.well-known/api-catalog` — RFC 9727

## Step 1 — Discover

- Protected Resource Metadata (RFC 9728): `GET /.well-known/oauth-protected-resource`
- Authorization Server Metadata (RFC 8414, includes the `agent_auth` block):
  `GET /.well-known/oauth-authorization-server`
- JWKS: `GET /.well-known/jwks.json`

## Step 2 — Register (anonymous, RFC 7591)

```http
POST /api/oauth/register
Content-Type: application/json

{"client_name": "my-agent"}
```

Response: `{ "client_id": "...", "client_secret": "...", "grant_types": ["client_credentials"] }`.
No human identity is required: the scope is read-only public data
(`identity_types_supported: ["anonymous"]`). Store the credentials; the secret
does not expire.

## Step 3 — Get a token

```http
POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=...&client_secret=...
```

Response: `{ "access_token": "<ES256 JWT>", "token_type": "Bearer", "expires_in": 3600, "scope": "read" }`.
`client_secret_basic` is also accepted. Verify tokens against /.well-known/jwks.json.

## Step 4 — Call the API

Send `Authorization: Bearer <access_token>` on `POST /api/mcp`. Valid token →
authenticated rate tier (per-client). Invalid/expired token → 401 with a
`WWW-Authenticate` header pointing back to the resource metadata: get a fresh
token and retry. No token → anonymous tier (per-IP), always available.

## What agents may NOT do

- No agent-native checkout: booking and payment are completed by the human user
  on the site. Never attempt to submit payment on a user's behalf.
- Customer/partner/admin areas are out of scope for agent credentials
  (scope is `read` only). The claim flow (/api/oauth/claim) is not required —
  and says so — until authenticated agent actions launch.

## Contact

https://centrestagepermis.fr/contact