# auth.md

You are an agent registering for RadarDeTrenes. This service exposes a public,
read-only rail data API at https://radardetrenes.com/api/v1 and publishes
agent registration metadata at the site root.

## Step 1 - Discover metadata

Fetch the Protected Resource Metadata document:

```http
GET /.well-known/oauth-protected-resource HTTP/1.1
Host: radardetrenes.com
Accept: application/json
```

Use the response fields as the source of truth:

- resource: https://radardetrenes.com/api/v1
- authorization_servers: https://radardetrenes.com
- scopes_supported: read:trains, read:stations
- bearer_methods_supported: header

Then fetch the Authorization Server metadata:

```http
GET /.well-known/oauth-authorization-server HTTP/1.1
Host: radardetrenes.com
Accept: application/json
```

Read the agent_auth block before choosing a registration method. It lists
skill, register_uri, claim_uri, revocation_uri, identity_types_supported, and
the credential_types_supported arrays for each supported method.

## Step 2 - Pick a method

If you have an ID-JAG or a verified email assertion for the user, use
identity_assertion. If you do not have a user identity, use anonymous
registration. Check the agent_auth metadata first; if your assertion type or
credential type is not listed there, stop or choose another supported method.

## Step 3 - Register

For an ID-JAG:

```http
POST /agent/auth HTTP/1.1
Host: radardetrenes.com
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "urn:ietf:params:oauth:token-type:id-jag",
  "assertion": "<id-jag>"
}
```

For a verified email assertion:

```http
POST /agent/auth HTTP/1.1
Host: radardetrenes.com
Content-Type: application/json

{
  "type": "identity_assertion",
  "assertion_type": "verified_email",
  "assertion": "user@example.com"
}
```

For anonymous registration:

```http
POST /agent/auth HTTP/1.1
Host: radardetrenes.com
Content-Type: application/json

{
  "type": "anonymous"
}
```

Successful registration returns an OAuth access_token scoped to the public
read-only API. If a response includes a claim_token, start the claim ceremony
at /agent/auth/claim before requesting post-claim scopes. Because the API is
public and read-only there are no post-claim scopes today, so registration
currently never returns a claim_token and you can proceed straight to Step 5.

## Step 4 - Claim ceremony

If registration returns a claim_token, start a claim attempt:

```http
POST /agent/auth/claim HTTP/1.1
Host: radardetrenes.com
Content-Type: application/json

{
  "claim_token": "<claim-token>",
  "email": "user@example.com"
}
```

Show the returned verification_uri and user_code to the user. The user signs in
on radardetrenes.com and enters the code there. Poll the token endpoint with the
claim grant only at the interval returned by the service.

## Step 5 - Use the credential

Present the access token with the bearer header:

```http
GET /api/v1/fleet HTTP/1.1
Host: radardetrenes.com
Authorization: Bearer <access-token>
```

Available scopes:

- read:trains - read live fleet, train route, and rolling-stock data.
- read:stations - read station, departure board, line, and alert data.

## Step 6 - Revocation and recovery

If an access token is rejected with invalid_grant or invalid_token, discard it
and restart discovery from /.well-known/oauth-protected-resource. Upstream
identity revocation events are advertised in agent_auth.events_supported and
received through the revocation URI published in Authorization Server metadata.

## Support

Project documentation: https://radardetrenes.com/llms-full.txt
Methodology, sources and legal notice: https://radardetrenes.com/sobre