Organizations API
The Organizations API manages organizations, their members, and email invitations. All endpoints require an authenticated session (cookie or Authorization: Bearer …) and are scoped to the current Application via X-App-Id / host context.
Organizations
| Method | Endpoint | Description |
|---|---|---|
POST | /api/organizations | Create a new organization (caller becomes first admin) |
GET | /api/organizations | List the caller's organizations (paginated) |
GET | /api/organizations/:id | Get organization details (member-only, 404 otherwise) |
PUT | /api/organizations/:id | Update name / slug / logo / metadata (admin-only) |
DELETE | /api/organizations/:id | Delete the organization (admin-only) |
Slugs are unique per application, 3–63 chars, ^[a-z](?:[a-z0-9-]*[a-z0-9])?$, no consecutive hyphens.
Members
| Method | Endpoint | Description |
|---|---|---|
GET | /api/organizations/:id/members | List members (any member) |
PUT | /api/organizations/:id/members/:user_id | Update a member's role (admin-only) |
DELETE | /api/organizations/:id/members/:user_id | Remove a member (admin-only) |
Role-change and remove endpoints return 409 if the action would leave the organization without an admin.
Invitations
| Method | Endpoint | Description |
|---|---|---|
POST | /api/organizations/:id/invitations | Create an invitation and email it (admin-only) |
GET | /api/organizations/:id/invitations | List invitations, optionally filtered by status (admin-only) |
DELETE | /api/organizations/:id/invitations/:invitation_id | Revoke a pending invitation (admin-only) |
POST | /api/organizations/accept-invitation | Accept an invitation with the emailed token (auth required) |
Invitation tokens are 64 hex characters. The accept endpoint requires the caller's email to match the invitation's email (case-insensitive). Email link target: {appPublicBaseUrl}/accept-org-invite?token=....
Audit Events
| Event type | Emitted on |
|---|---|
org_created | Successful create |
org_updated | Successful update |
org_deleted | Successful delete |
member_role_changed | Role updated |
member_removed | Member removed |
org_invitation_sent | Invitation created + emailed |
org_invitation_revoked | Invitation revoked |
org_invitation_accepted | Invitation accepted |
Active Organization
| Method | Endpoint | Description |
|---|---|---|
POST | /api/organizations/:id/activate | Switch the caller's active organization. Membership-only; re-mints the session JWT with an active_org_id claim and revokes the previous session row. Returns { ok: true, active_org_id, role }. |
Returns 404 to non-members and for organizations in other applications (deliberate — avoids cross-tenant probing). The active_org_id claim is a hint surfaced through GET /api/users/me; per-request authorization should still check organization_members so a forged or stale claim can't grant access.
Related
- Organizations — Overview and concepts
- Membership & Invitations — Membership and invitation flows
- Organization Roles — Role-based access within organizations