# Grilla auth.md

Grilla (https://grilla.fr) lets AI agents act for a Grilla user through OAuth 2.1, with the user's explicit consent. There is no agent-only signup and no API key for agents: a person with a Grilla account always approves the access.

- Resource server: `https://grilla.fr/api/mcp/compte` (MCP, Streamable HTTP)
- Authorization server (issuer): `https://grilla.fr`
- Public MCP server, no authorization needed: `https://grilla.fr/api/mcp`

## 1. Discover

1. Call the resource without a token: the `401` response carries `WWW-Authenticate: Bearer resource_metadata="…"`.
2. Read the protected resource metadata (RFC 9728): `https://grilla.fr/.well-known/oauth-protected-resource`.
3. Read the authorization server metadata (RFC 8414): `https://grilla.fr/.well-known/oauth-authorization-server` (also served as OpenID Connect discovery at `https://grilla.fr/.well-known/openid-configuration`).

## 2. Register the client

Supported method: OAuth 2.0 Dynamic Client Registration (RFC 7591), without an initial access token.

```http
POST https://grilla.fr/api/auth/oauth2/register
Content-Type: application/json

{"client_name": "My agent", "redirect_uris": ["http://127.0.0.1:33418/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "scope": "reports:read scans:write offline_access"}
```

The response contains your `client_id`. Redirect URIs are matched exactly. Registration is rate-limited.

Not supported: agent identity assertions (ID-JAG), anonymous agent registration, client credentials (machine-to-machine), API keys.

## 3. Get the user's authorization

Authorization code flow with PKCE (`S256`, mandatory for public clients). Send the user to the `authorization_endpoint` with `resource=https://grilla.fr/api/mcp/compte`. The user signs in to Grilla (an account is needed), then sees a consent page naming your client and the requested scopes. The access is granted for the organization the user is working in.

Scopes:

- `reports:read` : Lire les rapports d'analyse de votre organisation.
- `scans:write` : Lancer des analyses de pages (1 crédit par page).
- `offline_access` : receive a refresh token.

Exchange the code at the `token_endpoint`. Access tokens are JWTs valid 15 minutes, bound to `https://grilla.fr/api/mcp/compte`; refresh tokens are valid 14 days and rotate on use.

## 4. Use the token

Send `Authorization: Bearer <access_token>` to `https://grilla.fr/api/mcp/compte`. The tools you see depend on the granted scopes. Launching an analysis spends 1 credit of the organization's subscription; without a subscription or credits, the tool returns an explanatory error.

## Errors

| Response | Meaning | What to do |
|---|---|---|
| `401` with `WWW-Authenticate` | Missing, expired or invalid token | Refresh the token, or restart the authorization |
| `403` `insufficient_scope` | A scope is missing | Ask the user to authorize the scopes named in the challenge |
| `403` JSON-RPC error `-32001` | The user left the authorized organization | Restart the authorization |
| Tool error mentioning credits or subscription | No subscription or credits exhausted | Tell the user; do not retry |

## Revocation

Revoke tokens at the `revocation_endpoint` (RFC 7009). The user can also withdraw the access in Grilla, on the Équipe page (section « Agents IA autorisés »).

Documentation: https://grilla.fr/docs/agents-ia