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

# Organizations API

> Internal reference for the Organizations API — CRUD, member management, settings, and plan metadata.

> **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:

```ts theme={null}
// GET /api/organizations/current
// Returns: current active org based on session
// authMode: 'lightweight' — no extra DB round-trip
```

***

## Invitation Flow

```ts theme={null}
// 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'`.