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

# API de autenticación

> Referencia interna para la API de autenticación: controladores NextAuth.js, cambio de contexto de organización, flujos de enlace mágico/invitación y gestión de sesiones.

> **Documentación interna para desarrolladores.** Esta página cubre la capa de autenticación, la estructura de la sesión, el cambio de organización y los flujos de invitación. No está destinado a usuarios finales.

***

## Mapa de ruta

| Método     | Punto final               | Archivo de controlador                |
| ---------- | ------------------------- | ------------------------------------- |
| `GET/POST` | `/api/auth/[...nextauth]` | `app/api/auth/[...nextauth]/route.ts` |
| `GET/POST` | `/api/auth/update-org`    | `app/api/auth/update-org/route.ts`    |
| `GET/POST` | `/api/auth/invite`        | `app/api/auth/invite/route.ts`        |
| `GET/POST` | `/api/auth/admin-sync`    | `app/api/auth/admin-sync/route.ts`    |

***

## Controlador de autenticación siguiente

La ruta `[...nextauth]` es una envoltura delgada alrededor de `@zappway/lib/auth`:

```ts theme={null}
// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@zappway/lib/auth";

export const GET = async (req: NextRequest) => originalGet(req);
export const POST = async (req: NextRequest) => originalPost(req);
export const runtime = "nodejs";
```

La configuración de autenticación (proveedores, devoluciones de llamadas, estrategia de sesión) se encuentra en `@zappway/lib/auth`. Esta ruta sólo se delega en ella.

***

## Objeto de sesión (`AppRouteRequest.session`)

Todas las rutas autenticadas reciben un `AppRouteRequest` con un `session` completo:

```ts theme={null}
interface AppRouteRequest extends NextRequest {
  session: {
    user: {
      id: string;
      email: string;
      name: string;
    };
    organization: {
      id: string;
      slug: string;
      name: string;
    };
    locale: string;
    permissions: string[];
    membership: {
      id: string;
      role: string;
      accessGroupIds: string[];
    };
  };
  locale: string;
}
```

***

## Cambio de organización (`update-org`)

Los usuarios pueden pertenecer a varias organizaciones. El punto final `update-org` actualiza la organización activa en la sesión.

**Flujo:**

1. El usuario selecciona una organización diferente en la interfaz de usuario.
2. `POST /api/auth/update-org` se llama con el objetivo `organizationId`
3. El servidor valida que el usuario sea miembro de esa organización.
4. La cookie de sesión se actualiza con el nuevo contexto de la organización.

***

## Flujo de invitación (`invite`)

```
1. Admin invites a new user:
   POST /api/auth/invite { email, role, accessGroupId }
   → Creates a pending membership + sends email

2. Invitee clicks link in email
   GET /api/auth/invite?token=...
   → Validates token
   → Creates user (if new) or adds membership (if existing)
   → Redirects to dashboard
```

***

## Sincronización de administrador (`admin-sync`)

Punto final interno utilizado para sincronizar las membresías de organizaciones de nivel de administrador (por ejemplo, después de una actualización de plan). Se llama mediante webhooks de facturación a través de HTTP del lado del servidor (no desde el cliente).

***

## `withPermissionRoute` Modos de autenticación

| `authMode`                   | Descripción                                                          | Rendimiento                                                      |
| ---------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `'lightweight'`              | Utiliza sesión en caché solo desde el token                          | Rápido: sin viajes de ida y vuelta de DB adicionales             |
| `undefined` (predeterminado) | Validación de sesión completa, incluida la búsqueda de base de datos | Ligeramente más lento: verifica que la membresía aún esté activa |

Utilice `authMode: 'lightweight'` para todos los puntos finales de lectura para reducir la latencia.

***

## Patrón de verificación de permisos

```ts theme={null}
// Single permission
withPermissionRoute(req, { permission: 'agents.write' }, handler)

// Any of multiple permissions (OR logic)
withPermissionRoute(req, { anyPermission: ['agents.read', 'team.invite'] }, handler)
```

***

## Problemas conocidos / Problemas

* Se requiere **`runtime = "nodejs"`** en la ruta `[...nextauth]`: la biblioteca de autenticación utiliza API exclusivas de Node.js que no están disponibles en Edge Runtime.
* **Las cookies de sesión** son HTTPOnly y tienen como ámbito el dominio. Nunca intentes leerlos desde JS del lado del cliente.
* El punto final `update-org` debe invalidar cualquier conexión WebSocket/SSE activa para el usuario para que las actualizaciones en tiempo real reflejen el nuevo contexto de la organización.
* **La autenticación de enlace mágico** (si está habilitada a través de la biblioteca) es manejada internamente por el proveedor de correo electrónico de NextAuth; no hay una ruta `verify-magic-link` separada en esta aplicación.