# Auth.md

> Agent authentication for gabrimatic.info: how an AI agent registers and gets a token. Last updated: 2026-07-15.

Everything public on this site works without authentication: the JSON API, the page Markdown, and the MCP server's read tools. OAuth is here for agents that want scoped, token-based access anyway, and for anything gated in the future.

## Discover

- Authorization server metadata (RFC 8414): <https://www.gabrimatic.info/.well-known/oauth-authorization-server>
- Protected resource metadata (RFC 9728): <https://www.gabrimatic.info/.well-known/oauth-protected-resource>
- Signing keys, Ed25519 JWKS: <https://www.gabrimatic.info/.well-known/jwks.json>

## Register

Dynamic client registration (RFC 7591). No account, no approval queue, no claim ceremony; identity is anonymous.

```
POST https://www.gabrimatic.info/api/oauth/register
content-type: application/json

{ "client_name": "my-agent", "redirect_uris": ["http://127.0.0.1:8976/callback"] }
```

The response includes `client_id` and `client_secret`. Redirect URIs are limited to loopback http(s) or same-site HTTPS.

## Get a token

- Browser flow: `GET /api/oauth/authorize` with PKCE (S256 required). It auto-approves and 302-redirects with a short-lived code; exchange it at `POST /api/oauth/token`.
- Headless flow: `POST /api/oauth/token` with `grant_type=client_credentials`.

Access tokens are EdDSA-signed JWTs (`at+jwt`), valid 1 hour. Refresh tokens last 30 days. Scopes: `mcp:read`, `mcp:tools`.

## Use it

Send `Authorization: Bearer <token>` with `POST /api/mcp`. Anonymous calls work too; the token makes access explicit and auditable.

## Revocation

Tokens are short-lived and stateless; there is no revocation endpoint. Client secrets are derived, never stored, so rotating means registering again and letting old tokens expire.

## Metadata

The authorization server metadata at `/.well-known/oauth-authorization-server` carries the matching `agent_auth` block:

```json
{
  "agent_auth": {
    "skill": "https://www.gabrimatic.info/auth.md",
    "register_uri": "https://www.gabrimatic.info/api/oauth/register",
    "identity_types_supported": ["anonymous"],
    "credential_types_supported": ["client_secret"]
  }
}
```