# Auth.md

You are an agent. This document tells you how to register a credential for **tirrano.com** and authenticate. Follow the steps in order; do not skip ahead.

Endpoints live at `https://tirrano.com`.

## Step 1 — Register a credential

```http
POST /api/agents/register HTTP/1.1
Host: tirrano.com
Content-Type: application/json

{"name": "my-agent", "redirect_uris": ["https://my-agent.example.com/callback"]}
```

No authentication required.

Response (200):

```json
{
  "client_id": "agent_01ABC...",
  "client_secret": "sk_...",
  "token_type": "bearer"
}
```

What each field is:

- `client_id` — identifies your agent. Required for the token exchange (Step 2) and revocation (Step 4).
- `client_secret` — your bearer credential for the token endpoint. Returned exactly once. Persist it securely.
- `token_type` — always `bearer`.

## Step 2 — Use the credential

Exchange your `client_id` and `client_secret` for an access token:

```http
POST /api/oauth/token HTTP/1.1
Host: tirrano.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>&scope=read agent
```

Response (200):

```json
{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "read agent"
}
```

Pass the `access_token` as a Bearer token in subsequent requests:

```http
GET /api/formations HTTP/1.1
Host: tirrano.com
Authorization: Bearer <access_token>
```

## Step 3 — Revoke (optional)

```http
POST /api/agents/revoke HTTP/1.1
Host: tirrano.com
Content-Type: application/json

{"client_id": "<client_id>", "client_secret": "<client_secret>"}
```

## Discovery

- Registration endpoint: `https://tirrano.com/api/agents/register`
- Token endpoint: `https://tirrano.com/api/oauth/token`
- Revocation endpoint: `https://tirrano.com/api/agents/revoke`
- OAuth Authorization Server metadata: `https://tirrano.com/.well-known/oauth-authorization-server`
- OpenID Configuration: `https://tirrano.com/.well-known/openid-configuration`
- Protected Resource metadata: `https://tirrano.com/.well-known/oauth-protected-resource`

## Scopes

| Scope | Access |
|-------|--------|
| read | Public content, formations catalog |
| write | Submit forms, diagnostic results |
| agent | Full agent access, MCP tools |

## Rate limits

- Authenticated: 1000 req/min
- Unauthenticated: 60 req/min
