API de autenticação

Documentação interna para desenvolvedores. Esta página aborda a camada de autenticação, estrutura de sessão, alternância de organização e fluxos de convite. Não se destina a usuários finais.

​

Mapa de rotas

​

Manipulador NextAuth

// 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 sessão (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;
}

​

Mudança de organização (update-org)

1. O usuário seleciona uma organização diferente na IU
2. POST /api/auth/update-org é chamado com o destino organizationId
3. O servidor valida que o usuário é membro dessa organização
4. O cookie de sessão é atualizado com o novo contexto organizacional

​

Fluxo de convite (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

​

Sincronização de administrador (admin-sync)

​

withPermissionRoute Modos de autenticação

​

Padrão de verificação de permissão

// Single permission
withPermissionRoute(req, { permission: 'agents.write' }, handler)

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

​

Problemas conhecidos/pegadinhas

• runtime = "nodejs" é obrigatório na rota [...nextauth] — a biblioteca de autenticação usa APIs somente Node.js não disponíveis no Edge Runtime.
• Cookies de sessão são HTTPOnly e têm escopo no domínio. Nunca tente lê-los em JS do lado do cliente.
• O endpoint update-org deve invalidar quaisquer conexões WebSocket/SSE ativas para o usuário para que as atualizações em tempo real reflitam o novo contexto organizacional.
• Autenticação de link mágico (se habilitada por meio da biblioteca) é gerenciada internamente pelo provedor de e-mail do NextAuth - não há rota verify-magic-link separada neste aplicativo.