> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finzaria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.1

> Conecta apps y agentes a la cuenta de un usuario con OAuth 2.1 (authorization code + PKCE).

Usa **OAuth** cuando tu app o un agente actúa **a nombre de un usuario de Finzaria** (no de tu propia
cuenta). El usuario inicia sesión en Finzaria y **autoriza** tu app; tú recibes un access token que
usas igual que una API key: `Authorization: Bearer <access_token>`.

<Note>
  El uso principal de OAuth hoy es la **conexión de un click desde agentes** (Claude, ChatGPT) vía
  MCP — ese flujo lo maneja el cliente por ti. Si conectas un agente, ve directo a
  [MCP y agentes](/mcp/overview). Esta página es para apps que implementan el flujo a mano.
</Note>

## El flujo (authorization code + PKCE)

Finzaria implementa **OAuth 2.1**: solo *authorization code* con **PKCE obligatorio** (sin *implicit
grant*) y **redirect URIs de match exacto**.

<Steps>
  <Step title="Descubre los endpoints">
    El Authorization Server publica su metadata en
    `/.well-known/oauth-authorization-server` (RFC 8414). De ahí obtienes `authorization_endpoint`,
    `token_endpoint`, `registration_endpoint` y `jwks_uri`.
  </Step>

  <Step title="Registra tu cliente (DCR)">
    Registra tu app dinámicamente (RFC 7591) en el `registration_endpoint`, indicando tus
    `redirect_uris`. Recibes un `client_id`.
  </Step>

  <Step title="Manda al usuario a autorizar">
    Redirige a `authorization_endpoint` con `response_type=code`, tu `client_id`, `redirect_uri`,
    `scope` y el `code_challenge` (PKCE, método `S256`). El usuario inicia sesión en Finzaria y ve la
    **pantalla de consentimiento**; al aprobar, regresa a tu `redirect_uri` con un `code`.
  </Step>

  <Step title="Intercambia el code por tokens">
    Llama al `token_endpoint` con el `code` y el `code_verifier`. Recibes un **access token** y un
    **refresh token**.
  </Step>

  <Step title="Llama a la API">
    Usa el access token en `Authorization: Bearer …` contra `https://api.finzaria.com/v1`.
  </Step>
</Steps>

## Refresh tokens

Los access tokens son de vida corta. Renueva con el refresh token en el `token_endpoint`
(`grant_type=refresh_token`). Guarda el nuevo refresh token que recibas: la **rotación** invalida el
anterior — reusar uno viejo se trata como señal de robo y revoca la sesión.

## Seguridad

* **PKCE (`S256`) siempre**, incluso en clientes confidenciales.
* **Redirect URIs de match exacto** — regístralas completas, sin comodines.
* Nunca guardes tokens en almacenamiento accesible por terceros; trátalos como credenciales.
* El usuario puede **revocar** el acceso de tu app desde su cuenta en cualquier momento.

<Warning>
  OAuth está en **beta**. Los endpoints se descubren por metadata (no los hardcodees) y el
  comportamiento puede cambiar. Para producción con terceros, escríbenos antes de lanzar.
</Warning>