Auth API

Internal documentation for developers. This page covers the authentication layer, session structure, organization switching, and invite flows. Not intended for end users.

Route Map

Method	Endpoint	Handler File
`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`

NextAuth Handler

The [...nextauth] route is a thin wrapper around @zappway/lib/auth:

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

The auth config (providers, callbacks, session strategy) lives in @zappway/lib/auth. This route only delegates to it.

Session Object (`AppRouteRequest.session`)

All authenticated routes receive an AppRouteRequest with a populated 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;
}

Organization Switching (`update-org`)

Users can belong to multiple organizations. The update-org endpoint updates the active organization in the session. Flow:

User selects a different organization in the UI
POST /api/auth/update-org is called with the target organizationId
Server validates the user has a membership in that org
Session cookie is refreshed with the new org context

Invite Flow (`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

Admin Sync (`admin-sync`)

Internal endpoint used to synchronize admin-tier organization memberships (e.g., after a plan upgrade). Called by billing webhooks via server-side HTTP (not from the client).

`withPermissionRoute` Auth Modes

`authMode`	Description	Performance
`'lightweight'`	Uses cached session from token only	Fast — no extra DB round-trip
`undefined` (default)	Full session validation including DB lookup	Slightly slower — verifies membership is still active

Use authMode: 'lightweight' for all read endpoints to reduce latency.

Permission Check Pattern

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

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

Known Issues / Gotchas

runtime = "nodejs" is required on the [...nextauth] route — the auth library uses Node.js-only APIs not available in Edge Runtime.
Session cookies are HTTPOnly and scoped to the domain. Never try to read them from client-side JS.
The update-org endpoint must invalidate any active WebSocket/SSE connections for the user so that real-time updates reflect the new org context.
Magic link auth (if enabled via the lib) is handled by NextAuth’s email provider internally — there is no separate verify-magic-link route in this app.

API Internals

Infrastructure

Route Map

NextAuth Handler

Session Object (`AppRouteRequest.session`)

Organization Switching (`update-org`)

Invite Flow (`invite`)

Admin Sync (`admin-sync`)

`withPermissionRoute` Auth Modes

Permission Check Pattern

Known Issues / Gotchas

​Route Map

​NextAuth Handler

​Session Object (AppRouteRequest.session)

​Organization Switching (update-org)

​Invite Flow (invite)

​Admin Sync (admin-sync)

​withPermissionRoute Auth Modes

​Permission Check Pattern

​Known Issues / Gotchas

Route Map

NextAuth Handler

Session Object (`AppRouteRequest.session`)

Organization Switching (`update-org`)

Invite Flow (`invite`)

Admin Sync (`admin-sync`)

`withPermissionRoute` Auth Modes

Permission Check Pattern

Known Issues / Gotchas