# auth.md

You are an agent. Banklabs is a public French bank-comparison site. Public
agent APIs do **not** require registration or credentials. Follow this file
to confirm the access model, then call the APIs.

## Audience

Autonomous agents (LLM assistants, MCP clients, crawlers) that look for
`/auth.md` before deciding how to authenticate.

## Access model

| Aspect | Value |
| --- | --- |
| Identity required | None — `anonymous` |
| Credentials required | None for public agent APIs |
| Supported identity types | `anonymous` |
| Credential types | `access_token` (reserved; not issued today) |
| Registration | Not required. Reserved endpoints exist for discovery only. |

Public resources:

- Markdown of any page: `Accept: text/markdown` or `https://www.banklabs.fr/api/md/{path}`
- MCP (Streamable HTTP): `https://www.banklabs.fr/api/mcp`
- Status: `https://www.banklabs.fr/api/status`
- Catalog: `https://www.banklabs.fr/.well-known/api-catalog`
- ARD catalog: `https://www.banklabs.fr/.well-known/ai-catalog.json`

Do **not** POST to registration endpoints during a passive scan. Discovery
documents are the source of truth.

## Step 1 — Discover

### 1a. Protected Resource Metadata (RFC 9728)

```http
GET /.well-known/oauth-protected-resource
```

Canonical URL: https://www.banklabs.fr/.well-known/oauth-protected-resource

Fields: `resource` (this origin), `authorization_servers` (same origin),
`scopes_supported` (`read`), `bearer_methods_supported` (`header`).

### 1b. Authorization Server metadata (RFC 8414)

```http
GET /.well-known/oauth-authorization-server
```

Canonical URL: https://www.banklabs.fr/.well-known/oauth-authorization-server

Read `issuer` (must match the PRM resource) and the `agent_auth` block:
`skill`, `register_uri`, `identity_types_supported`, credential types,
`claim_uri`, and `revocation_uri`.

## Step 2 — Pick a method

Only **anonymous** is advertised. Banklabs does not accept ID-JAG
(`identity_assertion`) or verified-email (`service_auth`) registrations.

If you already have a user-supplied OAuth client secret, exchange it at
`https://www.banklabs.fr/oauth/token` with `grant_type=client_credentials`. No clients are
provisioned by default; that endpoint returns `invalid_client` until a
secret is configured. Public APIs still work without a token.

## Step 3 — Register (optional, reserved)

Registration is **not required**. The reserved registration surface is:

- `register_uri` / `identity_endpoint`: https://www.banklabs.fr/agent/auth
- `claim_uri` / `claim_endpoint`: https://www.banklabs.fr/agent/auth/claim
- `revocation_uri`: https://www.banklabs.fr/agent/auth/revoke

`POST https://www.banklabs.fr/agent/auth` with `{ "type": "anonymous" }` returns an error
explaining that anonymous read access needs no credential. Do not treat that
as a provisioning failure: continue with unauthenticated requests.

## Step 4 — Claim

No claim ceremony is active. `claim_uri` is reserved for a future
user-claimed flow. Skip this step.

## Step 5 — Credentials

No access token is issued for anonymous use. If you later hold a Bearer
token, send it as:

```http
Authorization: Bearer <access_token>
```

## Step 6 — Use the APIs

Call the public endpoints without credentials:

```bash
curl -H 'Accept: text/markdown' https://www.banklabs.fr/banques
curl https://www.banklabs.fr/api/md/banques
curl https://www.banklabs.fr/api/status
```

MCP tools (`get_page_markdown`, `list_banks`, `compare_banks`,
`get_fees_barometer`, `get_bank_fees`, `get_coverage`, `get_fee_history`,
`get_evidence`, `get_tariff_changes`, `get_promotions`,
`compare_annual_cost`) are listed
on `https://www.banklabs.fr/.well-known/mcp/server-card.json`.

Human documentation: https://www.banklabs.fr/docs/api

## Errors

| Code | Where | What to do |
| --- | --- | --- |
| `invalid_request` | `/agent/auth` | Registration is not required. Call public APIs without a token. |
| `invalid_client` | `/oauth/token` | No OAuth client is provisioned. Use anonymous public access. |
| `unsupported_response_type` | `/oauth/authorize` | Authorization-code / implicit flows are not offered. |

## Revocation

There is nothing to revoke for anonymous public access. `revocation_uri`
is reserved. If a future Bearer token returns 401, drop it and fall back to
unauthenticated public APIs.
