> ## 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 autenticação

> Referência interna para a API Auth – manipuladores NextAuth.js, troca de contexto de organização, fluxos de link mágico/convite e gerenciamento de sessã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

| Método     | Ponto final               | Arquivo manipulador                   |
| ---------- | ------------------------- | ------------------------------------- |
| `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`    |

***

## Manipulador NextAuth

A rota `[...nextauth]` é um invólucro fino em torno 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";
```

A configuração de autenticação (provedores, retornos de chamada, estratégia de sessão) reside em `@zappway/lib/auth`. Esta rota apenas delega a ela.

***

## Objeto de sessão (`AppRouteRequest.session`)

Todas as rotas autenticadas recebem um `AppRouteRequest` com um `session` preenchido:

```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;
}
```

***

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

Os usuários podem pertencer a diversas organizações. O endpoint `update-org` atualiza a organização ativa na sessão.

**Fluxo:**

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`)

Endpoint interno usado para sincronizar associações de organização de nível administrativo (por exemplo, após uma atualização de plano). Chamado por webhooks de cobrança via HTTP do lado do servidor (não do cliente).

***

## `withPermissionRoute` Modos de autenticação

| `authMode`           | Descrição                                                          | Desempenho                                                      |
| -------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- |
| `'lightweight'`      | Usa sessão em cache apenas do token                                | Rápido - sem ida e volta extra ao banco de dados                |
| `undefined` (padrão) | Validação completa da sessão, incluindo pesquisa de banco de dados | Um pouco mais lento — verifica se a associação ainda está ativa |

Use `authMode: 'lightweight'` para todos os endpoints de leitura para reduzir a latência.

***

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

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