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

# Autenticación

> Tokens de acceso personal, tokens JWT Bearer y OAuth 2.0 para la API y el servidor MCP de iZap.

La API REST acepta un token de acceso personal como credencial Bearer en cada
solicitud. El servidor MCP y la API REST también comparten un único servidor de
autorización OAuth 2.0, montado en `{origin}/oauth`, para los clientes que
actúan en nombre de un usuario.

## Tokens de acceso personal (recomendado)

Para scripts, servicios backend y cualquier otra cosa que llame directamente a
la API REST, usa un token de acceso personal (PAT) en lugar de un flujo de
login:

```
Authorization: Bearer izap_pat_...
```

Crea uno desde el Dashboard: **Tu configuración → Claves API**. El token se
muestra una sola vez, al crearlo: guárdalo en un gestor de secretos o en una
variable de entorno, nunca en el control de versiones. Los tokens de acceso
personal están disponibles en los planes que incluyen la API REST; puedes
revocar un token desde la misma pantalla en cualquier momento, y la revocación
tiene efecto inmediato.

## Token rápido (scripts de servidor a servidor)

Para un script puntual o pruebas locales, intercambia las credenciales de la
cuenta por un JWT de corta duración en lugar de crear un PAT:

```bash theme={null}
curl -X POST "https://api.izap.ai/api/v1/auth/jwt/login" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=$IZAP_EMAIL&password=$IZAP_PASSWORD"
# -> {"access_token":"<JWT>","token_type":"bearer"}
```

Luego envíalo en cada solicitud, igual que un token de acceso personal:

```
Authorization: Bearer <access_token>
```

Esto es también lo que usan internamente las recetas de `@izapai/wizard` cuando
generan un cliente rápido. Para cualquier cosa que dure más que un script,
prefiere un token de acceso personal.

## OAuth 2.0 (aplicaciones de terceros)

Usa el flujo authorization code + PKCE para los clientes que actúan en nombre de
un usuario.

### Discovery

Los clientes descubren el servidor de autorización mediante documentos de
metadatos estándar:

| Documento | Ruta |
| - | - |
| Metadatos del servidor de autorización | `/.well-known/oauth-authorization-server` |
| Metadatos del recurso protegido (MCP) | `/.well-known/oauth-protected-resource/mcp` |

El endpoint del MCP devuelve `401` con un encabezado `WWW-Authenticate`, así que
los clientes MCP que cumplen la especificación inician el flujo OAuth
automáticamente.

### Flujo

1. `GET /oauth/authorize` con `response_type=code`, `client_id`,
   `redirect_uri`, `code_challenge`, `code_challenge_method=S256` y `state`.
2. El usuario se autentica y aprueba; iZap redirige de vuelta con `code`.
3. `POST /oauth/token` con `grant_type=authorization_code`, `code`,
   `redirect_uri` y `code_verifier` → devuelve un `access_token` (JWT) y un
   `refresh_token`.

Los clientes públicos pueden registrarse por su cuenta mediante
`POST /oauth/register`. Renueva un token expirado con
`grant_type=refresh_token`.

## Notas sobre los tokens

* Todo token —token de acceso personal, JWT o token de acceso OAuth— es un
  secreto. Léelo desde una variable de entorno o un gestor de secretos, nunca lo
  escribas directamente en el código.
* Un token de acceso personal no expira por sí solo; es válido hasta que lo
  revoques desde el Dashboard.
* Los JWT y los tokens de acceso OAuth expiran. Renuévalos (con un nuevo login o
  con el grant de refresh de OAuth) cuando una solicitud devuelva `401`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.