# Soobrief Agent Authentication & Integration Guide

Soobrief (`https://soobrief.com`) provides machine-readable endpoints and autonomous agent tools for ingesting completed project management tasks and synthesizing deterministic weekly product updates and changelogs.

## Service Endpoints

- **Web Origin:** `https://soobrief.com`
- **API Origin:** `https://api.soobrief.com`
- **MCP Server Endpoint:** `https://api.soobrief.com/v1/mcp/sse`
- **API Catalog:** `https://soobrief.com/.well-known/api-catalog`
- **OpenAPI Specification:** `https://api.soobrief.com/v1/openapi.json`
- **OAuth 2.0 Authorization Server:** `https://soobrief.com/.well-known/oauth-authorization-server`
- **OAuth 2.0 Protected Resource:** `https://soobrief.com/.well-known/oauth-protected-resource`

## Authentication Models

### 1. User & Human In The Loop (Session Auth)
Authentication is powered by self-hosted Better Auth with Soobrief's own PostgreSQL database as source of truth. Users authenticate via:
- Email and password
- Google Social Auth proxying through `https://soobrief.com/login`

Cookies: `better-auth.session_token` (HTTP-only, Secure, SameSite=Lax).

### 2. Autonomous Agents & MCP (Bearer Token Auth)
AI Agents operating via MCP or direct REST API communicate using OAuth 2.0 Bearer tokens:

```http
Authorization: Bearer <session_or_api_token>
```

#### Supported Scopes
- `tasks:read`: Query ingested completed tasks across connected providers.
- `notes:read`: Retrieve generated weekly product notes and changelogs.
- `notes:write`: Trigger generation or update draft release notes.
- `publications:read`: Access published changelogs and public widget feeds.

### 3. Agent Registration & Dynamic Onboarding
To register an autonomous workflow with a Soobrief workspace:
1. Obtain workspace authorization by directing the human workspace owner to `https://soobrief.com/login`.
2. Following OAuth 2.0 PKCE exchange or session token issuance, authenticate all subsequent API calls via `Authorization: Bearer <token>`.
3. Read the API catalog at `/.well-known/api-catalog` to discover live endpoints.

## Content Negotiation for Agents
Autonomous agents requesting human-readable documentation in markdown format should send:

```http
Accept: text/markdown
```

The server returns pure markdown with `Content-Type: text/markdown; charset=utf-8` and an `x-markdown-tokens` estimate header.