API de autenticación

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

​

Controlador de autenticación siguiente

// 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";

​

Objeto de sesión (AppRouteRequest.session)

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)

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)

​

withPermissionRoute Modos de autenticación

​

Patrón de verificación de permisos

// 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.