# auth.md

This document tells AI agents how to authenticate with the firatempsdevi.cat APIs.

> **Status: scaffolding.** The OAuth endpoints referenced below are published for
> discovery completeness but are **not yet live**. Do not rely on them for
> production agent authentication until the authorization server is deployed.

## Audience

Automated agents that need to call protected endpoints on `https://firatempsdevi.cat`.
Public read endpoints (see [`/openapi.json`](/openapi.json)) require no
authentication.

## Discovery documents

- Protected resource metadata: [`/.well-known/oauth-protected-resource`](/.well-known/oauth-protected-resource)
- Authorization server metadata: [`/.well-known/oauth-authorization-server`](/.well-known/oauth-authorization-server)
- OpenID configuration: [`/.well-known/openid-configuration`](/.well-known/openid-configuration)
- JSON Web Key Set: [`/.well-known/jwks.json`](/.well-known/jwks.json)

## Registration

Agents obtain credentials via dynamic client registration at the `register_uri`
advertised in the authorization server metadata (`agent_auth.register_uri`):

```
POST https://firatempsdevi.cat/oauth/register
```

## Obtaining a token

1. Register (above) to receive a `client_id` / `client_secret`.
2. Run the OAuth 2.0 Authorization Code flow with PKCE (`S256`) against the
   `authorization_endpoint` and `token_endpoint`.
3. Present the access token in the `Authorization: Bearer <token>` header.

## Supported identity types

- `anonymous` — agents acting without an end-user identity.