# Bri Auth

Bri has two agent-facing auth paths. Neither path is a public OAuth app
registration surface for arbitrary third-party developers; tokens are issued
through Bri-owned Skill, CLI, browser, or approved connector flows.

## 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.