# auth.md

Bri supports agent registration for authorized agents that need to act on
behalf of a user through the Bri Skill, CLI, browser handoff, or approved MCP
connector flows.

## Discovery

Fetch the root protected resource metadata first:

```text
https://bri.so/.well-known/oauth-protected-resource
```

Then fetch the authorization server metadata advertised there:

```text
https://bri.so/.well-known/oauth-authorization-server
```

The authorization server metadata includes an `agent_auth` block with the
registration endpoint, supported identity types, credential types, claim URL,
and revocation URL.

## Agent Registration

Dynamic OAuth client registration is available at:

```text
https://bri.so/api/auth/oauth2/register
```

Bri currently supports anonymous agent registration for pre-claim work:

```http
POST /api/v1/auth/skill/anonymous HTTP/1.1
Host: bri.so
Content-Type: application/json
```

The response returns a `Bearer` Skill Session token. To claim that work for a
signed-in user, send the user through the pair-code handoff:

```text
https://bri.so/pair
```

Use the OAuth revocation endpoint to revoke OAuth-issued tokens:

```text
https://bri.so/api/auth/oauth2/revoke
```

## Public API

Public `/api/v1` routes use a Bri Skill Session bearer token.

```http
POST /api/v1/subscriptions/list HTTP/1.1
Host: bri.so
Authorization: Bearer bri_skill_session_token
Content-Type: application/json

{"limit":10}
```

Agents can start at `/signin` or use `/pair` for Skill handoff. Skill Session bearer tokens are scoped to the signed-in user and are checked by route handlers and services before reading or mutating user data.

## MCP

The MCP connector is at `POST /mcp` and requires an OAuth bearer token for the MCP resource with scope `mcp:use`.

Protected resource metadata:

```text
https://bri.so/.well-known/oauth-protected-resource/mcp
```

Unauthenticated MCP requests return `401` with a `WWW-Authenticate` header that includes `resource_metadata`.

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", resource="https://bri.so/mcp", resource_metadata="https://bri.so/.well-known/oauth-protected-resource/mcp"
Content-Type: application/json
```

## Recovery

- Retry transient `429` and `5xx` responses with exponential backoff.
- Do not retry `400` validation errors until the request body changes.
- Treat `401` as a missing, expired, or wrong-audience token.
- Treat `403` as an authorization or scope failure.