Organizations API

Internal documentation for developers. This page covers organization management endpoints, membership operations, and settings management. Not intended for end users.

Route Map

Method	Endpoint	Handler File	Description
`GET`	`/api/organizations`	`organizations/route.ts`	List orgs for current user
`POST`	`/api/organizations`	`organizations/route.ts`	Create a new organization
`GET`	`/api/organizations/[id]`	`organizations/[id]/route.ts`	Get organization by ID
`PATCH`	`/api/organizations/[id]`	`organizations/[id]/route.ts`	Update organization settings
`DELETE`	`/api/organizations/[id]`	`organizations/[id]/route.ts`	Delete organization
`GET`	`/api/organizations/current`	`organizations/current/route.ts`	Get current active organization
`GET`	`/api/organizations/[id]/invite`	`organizations/[id]/invite/route.ts`	List pending invitations
`POST`	`/api/organizations/[id]/invite`	`organizations/[id]/invite/route.ts`	Send invitation

Auth Pattern

Organization endpoints use standard withPermissionRoute. Most org-level write operations require org.manage or admin-tier permissions. Org isolation is enforced at the session level: req.session.organization.id is the active org. Cross-org access is blocked by the permission layer.

Current Organization

The current endpoint is a lightweight helper used by the frontend to get the active org without knowing its ID upfront:

// GET /api/organizations/current
// Returns: current active org based on session
// authMode: 'lightweight' — no extra DB round-trip

Invitation Flow

// POST /api/organizations/[id]/invite
// Body: { email: string, accessGroupId: string, role?: string }
// 1. Creates pending Membership with status='invited'
// 2. Sends invitation email via @zappway/lib/email
// 3. Returns { invitation, membership }

Invitation tokens are short-lived (72 hours by default). After expiry, the invitee must be re-invited.

Org Settings (PATCH)

The PATCH /api/organizations/[id] endpoint accepts:

Field	Type	Description
`name`	`string`	Display name
`logo`	`string`	Logo URL
`timezone`	`string`	Default timezone
`locale`	`string`	Default locale (`en`, `pt-BR`, `es`)
`allowedDomains`	`string[]`	Restrict signups to these email domains

Known Issues / Gotchas

Organization deletion is a destructive operation that cascades to ALL org resources (agents, contacts, conversations, datastores). Protected by a confirmation step in the UI. Backend must verify the DELETE is intentional.
current endpoint must be invalidated/re-fetched after update-org (auth session switch).
Multi-org users see multiple orgs in the org selector. The GET /api/organizations list is scoped to memberships where status='active'.

API Internals

Infrastructure

Route Map

Auth Pattern

Current Organization

Invitation Flow

Org Settings (PATCH)

Known Issues / Gotchas

​Route Map

​Auth Pattern

​Current Organization

​Invitation Flow

​Org Settings (PATCH)

​Known Issues / Gotchas

Route Map

Auth Pattern

Current Organization

Invitation Flow

Org Settings (PATCH)

Known Issues / Gotchas