# Auth.md

## Collej Authentication Guide

Collej uses passwordless **Bearer Token** authentication (`Authorization: Bearer <token>`) and **OAuth 2.1 with PKCE (S256)** across Web, Mobile, OpenAPI, and MCP.

## 1. OAuth 2.1 with PKCE & Dynamic Client Registration (Recommended for MCP & Mobile)
- **Authorization Server Metadata**: `https://app.collej.me/.well-known/oauth-authorization-server`
- **Protected Resource Metadata**: `https://app.collej.me/.well-known/oauth-protected-resource`
- **Dynamic Client Registration**: `POST https://app.collej.me/api/oauth/register`
- **Authorization Endpoint**: `GET https://app.collej.me/oauth/authorize`
- **Token Endpoint**: `POST https://app.collej.me/api/oauth/token`
- **Revocation Endpoint**: `POST https://app.collej.me/api/oauth/revoke`
- **Scopes**: `colleges:read`, `records:read`, `records:write`, `favorites:write`, `chat:write`, `account:manage`

## 2. Personal Access Tokens (PAT)
- Generate a `collej_pat_...` token in the Collej UI footer under **API & MCP** or via `POST https://app.collej.me/api/auth/tokens`.

## 3. Passwordless User Sign-In
- **Email 6-digit OTP / Magic Link**: `POST https://app.collej.me/api/auth/email/start` -> `POST https://app.collej.me/api/auth/email/verify`
- **Sign in with Google (OIDC)**: `GET https://app.collej.me/api/auth/google/start` or `POST https://app.collej.me/api/auth/google/token`
