# Autenticación de la API de PUC Colombia (para agentes)

Esta guía (formato `auth.md`) explica cómo un agente obtiene credenciales y llama a la API REST de PUC Colombia. Hay dos métodos: **OAuth 2.1** (para actuar en nombre de un usuario) y **service_auth** con API key (máquina a máquina).

## Discover

- Recurso protegido (RFC 9728): https://puccol.com/.well-known/oauth-protected-resource
- Authorization server (RFC 8414): https://puccol.com/.well-known/oauth-authorization-server
- Un `401` de la API incluye `WWW-Authenticate: Bearer resource_metadata="https://puccol.com/.well-known/oauth-protected-resource"`.

El bloque `agent_auth` de la metadata declara el `identity_endpoint` (https://puccol.com/api/agent/identity) y los `identity_types_supported`. La `identity_assertion` (ID-JAG, `urn:ietf:params:oauth:token-type:id-jag`) aún NO está soportada; usa OAuth o service_auth.

## Pick a method

- **OAuth 2.1** (authorization_code + PKCE): cuando el agente actúa por un usuario. El proveedor de identidad es el OAuth Server de Supabase.
- **service_auth** (API key): integraciones máquina a máquina sin usuario. Cabecera `x-api-key`.

## Register

- OAuth: registra un cliente OAuth. El authorization server soporta **Dynamic Client Registration** cuando está habilitado. Emisor (issuer): `https://vtlfdeoprrdcoqtyzahf.supabase.co/auth/v1`.
- service_auth: crea una cuenta en https://puccol.com, inicia sesión y genera una API key en https://puccol.com/perfil/api (plan gratuito: 3 solicitudes/día).

## Claim

- OAuth: dirige al usuario al `authorization_endpoint` (`https://vtlfdeoprrdcoqtyzahf.supabase.co/auth/v1/oauth/authorize`) con `response_type=code`, `code_challenge` (**S256**), `redirect_uri` y `scope`. Scopes de la API: `puc.read reportes.read indicadores.read` (y `indicadores.full` en planes de pago), además de los OIDC `openid email profile`.

## Exchange

- OAuth: intercambia el `code` + `code_verifier` en el `token_endpoint` (`https://vtlfdeoprrdcoqtyzahf.supabase.co/auth/v1/oauth/token`) por un `access_token` (JWT).

## Use the access_token

- Envía `Authorization: Bearer <access_token>` (OAuth) o `x-api-key: <API key>` (service_auth) en cada solicitud a `https://puccol.com/api/v1/...`. Contrato: https://puccol.com/openapi.json.

## Errors

- `401` credencial ausente/ inválida (incluye `WWW-Authenticate`). `402` el plan no incluye API. `429` cuota superada (ver `Retry-After`). Todos los errores: `{ "error": { "code", "message" } }`.

## Revocation

- OAuth: los refresh tokens rotan; revoca la sesión desde el proveedor de identidad. service_auth: revoca la API key en https://puccol.com/perfil/api.