# auth.md

You are an agent. **depanneuse-sos.fr** (éditeur Aquylis) supports **agentic registration** for its public APIs: discover → register → (claim if needed) → exchange for an access_token → call API → handle revocation. Follow the steps in order.

Resource server / site: `https://depanneuse-sos.fr`  
Authorization server (same origin): `https://depanneuse-sos.fr`  
Primary scopes: `geo:read`, `health:read`

## Step 1 — Discover

### 1a. Protected Resource Metadata

```http
GET https://depanneuse-sos.fr/.well-known/oauth-protected-resource
```

Expected fields: `resource` (`https://depanneuse-sos.fr/`), `authorization_servers`, `scopes_supported`, `bearer_methods_supported: ["header"]`.

### 1b. Authorization Server metadata

```http
GET https://depanneuse-sos.fr/.well-known/oauth-authorization-server
```

Read `issuer`, `token_endpoint`, `revocation_endpoint`, `grant_types_supported`, and the `agent_auth` block (`skill`, `register_uri` / `identity_endpoint`, `claim_uri`, identity types).

OpenID Connect discovery is also published at `/.well-known/openid-configuration`.

## Step 2 — Pick a method

1. **ID-JAG / identity_assertion** — if your provider can mint `urn:ietf:params:oauth:token-type:id-jag` for audience `https://depanneuse-sos.fr/`.
2. **verified_email** — email claim ceremony via `agent_auth.claim_uri`.
3. **anonymous** — register without a user identity; claim later if ownership is needed.

## Step 3 — Register

```http
POST https://depanneuse-sos.fr/agent/identity
Content-Type: application/json
```

Body shapes (one of):

- `{ "type": "identity_assertion", "assertion": "<ID-JAG>" }`
- `{ "type": "service_auth", "login_hint": "user@example.com" }`
- `{ "type": "anonymous" }`

Surface `resource_name` from PRM to the user before asserting identity (skip for anonymous).

## Step 4 — Claim (when required)

```http
POST https://depanneuse-sos.fr/agent/identity/claim
Content-Type: application/json
```

Use the `claim_token` / verification URI returned by the service. Poll completion as described in the WorkOS auth.md profile.

## Step 5 — Exchange for access_token

```http
POST https://depanneuse-sos.fr/oauth/token
Content-Type: application/x-www-form-urlencoded
```

- `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer` + `assertion=<identity_assertion>`
- or `grant_type=urn:workos:agent-auth:grant-type:claim` while polling a claim

## Step 6 — Call APIs

```http
GET https://depanneuse-sos.fr/api/health
Authorization: Bearer <access_token>
```

```http
GET https://depanneuse-sos.fr/api/geo/search?q=Marseille
Authorization: Bearer <access_token>
```

Public discovery documents (OpenAPI, MCP card, ARD catalog) remain readable without a token.

## Step 7 — Revocation

```http
POST https://depanneuse-sos.fr/oauth/revoke
```

Upstream identity revocation events may be pushed to `agent_auth.events_endpoint`.

## References

- Skill URL: `https://depanneuse-sos.fr/auth.md`
- PRM: [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)
- Auth.md profile: https://workos.com/auth-md
- OpenAPI: `https://depanneuse-sos.fr/.well-known/openapi.yaml`
- ARD catalog: `https://depanneuse-sos.fr/.well-known/ai-catalog.json`