> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt). # Organizations API Organizations API [#organizations-api] These endpoints manage any organization and need a platform admin's bearer token or [platform key](../api-basics/authentication); `org_id` is a UUID. For a step-by-step setup, see [Set up a client](../workspaces/set-up-a-client). Endpoints [#endpoints] | Method | URL | Input | Does | Auth | | ------------------ | --------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------- | | `GET` | `/api/v1/platform-admin/organizations/` | `?search=&page=&page_size=` | List | Platform key or bearer | | `POST` | `/api/v1/platform-admin/organizations/` | `{name, admin_email}` | Create, and invite its first admin; returns `{organization, admin: {invite}}` | Platform key or bearer | | `GET` · `PATCH` | `/api/v1/platform-admin/organizations/{org_id}/` | [Edit fields](#edit-fields) | Read · edit | Platform key or bearer | | `DELETE` | `/api/v1/platform-admin/organizations/{org_id}/` | | Delete (see below) | Platform key or bearer | | `DELETE` | `/api/v1/platform-admin/organizations/{org_id}/deletion/` | | Cancel a scheduled deletion | Platform key or bearer | | `GET` | `…/{org_id}/members/` | | List members | Platform key or bearer | | `POST` | `…/{org_id}/members/` | `{emails, role?, external?}`, up to 500 emails | Add existing accounts without an invite (see [Members](#members)); returns `{added, skipped}` | Platform key or bearer | | `PATCH` · `DELETE` | `…/{org_id}/members/{membership_id}/` | `{role}` | Change [organization role](#organization-roles) · remove. `membership_id` comes from the members list | Platform key or bearer | | `GET` · `POST` | `…/{org_id}/invites/` | `{email, role?, seat_tier_slug?, external?}` | List · invite; `role` defaults to the organization's default role. Returns `{invite}` | Platform key or bearer | | `DELETE` | `…/{org_id}/invites/{invite_id}/` | | Revoke an invite | Platform key or bearer | | `GET` · `POST` | `…/{org_id}/member-roles/` | `{name, workspace_limit?}` | List · create an [organization role](#organization-roles) | Platform key or bearer | | `PUT` | `…/{org_id}/member-roles/{slug}/` | `{workspace_limit}` | Set how many workspaces the role may create: a number from 0, or `null` for no limit | Platform key or bearer | | `PUT` | `…/{org_id}/member-roles/{slug}/default/` | | Make it the role new members get | Platform key or bearer | | `DELETE` | `…/{org_id}/member-roles/{slug}/` | | Delete a custom organization role; `204` | Platform key or bearer | | `GET` · `POST` | `…/{org_id}/roles/` | `{name}` | List workspace roles · create a custom [workspace role](#workspace-roles) | Platform key or bearer | | `GET` | `…/{org_id}/roles/permissions/` | | List permissions | Platform key or bearer | | `PUT` | `…/{org_id}/roles/{role_id}/permissions/{permission_id}/` | `{enabled}` | Turn a permission on or off for a role | Platform key or bearer | | `DELETE` | `…/{org_id}/roles/{role_id}/` | | Delete a custom role | Platform key or bearer | | `POST` | `/api/v1/platform-admin/spaces/` | `{name, organization_id}` | Create a workspace inside the organization | Platform key or bearer | | `PUT` | `/api/v1/platform-admin/spaces/{slug}/organization/` | `{organization_id}` | Move a workspace in; its creator must be a home member | Platform key or bearer | | `DELETE` | `/api/v1/platform-admin/spaces/{slug}/organization/` | | Move a workspace out; see [Move a workspace out](#move-a-workspace-out) | Platform key or bearer | | `POST` | `/api/v1/platform-admin/spaces/{slug}/organization/move-out-preview/` | | What moving it out changes, without moving it | Platform key or bearer | Edit fields [#edit-fields] `PATCH` changes only the fields you send. | Field | Rule | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | 1–255 characters; cannot be `null` | | `address_line1`, `address_line2`, `city`, `state_or_province` | Up to 255 characters | | `postal_code` | Up to 32 characters | | `country` | Two-letter code such as `DE`; lowercase is accepted | | `start_pages` | Where members land; see [Start pages](#start-pages). Replaces the whole object | | `members_can_join_other_organizations` | `true` lets home members be external members elsewhere and join workspaces outside the organization; default `false`. Turning it off keeps the memberships they have | An empty string clears an address field. Start pages [#start-pages] `start_pages` decides whether a member opens Alomana on a new chat (`chat`) or on the Overview of their agents, apps and recent chats (`overview`). ```json { "start_pages": { "default": "chat", "organization_roles": { "intern": "overview" }, "workspace_roles": { "member": "overview" } } } ``` | Field | Rule | | -------------------- | -------------------------------------------------------------------------------------------- | | `default` | `chat` or `overview`; `chat` when left out | | `organization_roles` | Organization role slug → page. Slugs from `…/member-roles/` | | `workspace_roles` | Workspace role slug → page: `member`, `editor`, `admin` or a custom role of the organization | * For the workspace a person has open, the first match wins: their workspace role, then their organization role, then `default`. * Workspaces outside the organization, and people in no organization, always open on chat. * A page other than `chat` or `overview`, or a role the organization does not have: `422`. * Deleting a role removes its entry, so a new role with the same name starts on the default. * `GET …/{org_id}/` returns `start_pages`; an organization that never set one returns `{"default": "chat", "organization_roles": {}, "workspace_roles": {}}`. Organization roles [#organization-roles] The role a person holds in the organization itself, listed by `…/member-roles/` as `{slug, name, workspace_limit, built_in, default}`. Only `admin` can manage the organization. | Role | Rules | | -------- | --------------------------------------------------------------------------------------------------------- | | `admin` | Fixed: never limited, never the default, cannot be deleted | | `member` | Built in; no workspace limit until you set one; cannot be deleted | | Custom | `slug` is the name slugified and cannot change; a new role's `workspace_limit` is `0` unless you send one | * `workspace_limit` counts the active workspaces the person created in this organization; reaching it makes `POST /api/v1/spaces/` return `403`. A person's first workspace is never limited. * The default role starts as `member`. Invites and direct adds without `role` get it. * A name that is `admin`, `member` or already taken: `409` `ORGANIZATION_ROLE_EXISTS`. * Deleting `admin` or `member`: `409` `BUILT_IN_ORGANIZATION_ROLE`. Deleting the default role, or one held by a member or a pending invite: `409` `ORGANIZATION_ROLE_IN_USE`. * A `role` the organization does not have, on a member, invite or direct add: `422`. Workspace roles [#workspace-roles] * Built-in roles `member`, `editor` and `admin` can be changed for the organization; custom roles appear in every workspace of the organization, now and later. * A workspace inherits the organization's changes; its own changes win over them. See [Roles and permissions](../workspaces/roles-and-permissions). * A custom role still held by a member or a pending invite cannot be deleted: `409`. * Built-in roles cannot be deleted: `409`. Members [#members] Organization members are separate from workspace members; add people to each workspace with [Members and invites](../workspaces/members-and-invites). A person has at most one **home** organization and can be an **external** member of others: | Membership | Rules | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Home (`external: false`) | Pays for them: only a home member holds a seat or plan. Its policy applies to them everywhere | | External (`external: true`) | Any number. No seat or plan; their home pays. The organization's roles, model blocks and the member role's workspace limit apply to them in its workspaces | An invite never adds anyone directly, also not an existing account: only the invitee can accept, because they decide whether to switch their home and which workspaces to bring. Joining moves no workspace and removes no workspace membership. See [Organizations and workspaces](../workspaces/organizations-and-workspaces). The same rules apply to `admin_email` when an organization is created. | Case | Result | | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Any email, with or without a seat | Invite email and a `pending` invite in `invite`; a seat is charged on accept | | User already a member of this organization | `409` `User is already a member of this organization` | | External member of this organization, invited as external | `409`; a home invite is allowed and makes this their home on accept | | User whose home is another organization | Allowed; the invitee decides on accept, and you are not told | | `external: true` with `seat_tier_slug` | `422`; a seat goes only to home members | | A seat or plan for an external member | `409` `EXTERNAL_MEMBER` | | User paying for a personal plan, added without a seat | `409` `SEAT_REQUIRED_FOR_PERSONAL_PAYER` | | `seat_tier_slug` is not an active organization plan | `422` `'' is not a organization plan` | | A seat is given while the organization's deletion is scheduled | `409` `ORGANIZATION_ENDING` | | Removing or demoting the last admin | `409` `LAST_ORGANIZATION_ADMIN` | Organization invites expire after 7 days by default; a new invite to the same email revokes the earlier pending one. Accepting [#accepting] The invitee, signed in, accepts with `POST /api/v1/organizations/invites/accept` and `{token}`, or `POST /api/v1/organizations/invites/{invite_id}/accept/`. Optional fields: | Field | Effect | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace_slugs` | Workspaces the invitee created, belongs to and no organization holds; they move into this organization. A home invite only; others are ignored | | `switch_home` | Required when a home invite reaches someone with a home elsewhere; without it, `409` `{"code": "HOME_SWITCH_REQUIRED", "organization_name"}` names the current home. The old home becomes external and its seat is released | | `replace_personal_plan` | Required when an invite with a seat reaches someone paying for a personal plan | An external invite to someone whose home has `members_can_join_other_organizations` off returns `409` `{"code": "HOME_ORGANIZATION_CONTAINED", "organization_name"}`. `GET /api/v1/organizations/mine/` lists the caller's memberships, home first, as `{id, name, role, role_name, external}`. Add existing accounts without an invite [#add-existing-accounts-without-an-invite] `POST …/{org_id}/members/` brings a customer's existing accounts in at once, or your own staff as `external: true`. It sends no email, moves no workspace and removes no workspace membership; move home members' workspaces in afterwards with `PUT /api/v1/platform-admin/spaces/{slug}/organization/`. Each email lands in `added`, or in `skipped` as `{email, reason}`: | `reason` | Means | | -------------------- | ---------------------------------------------------------------------- | | `not_found` | No account has this email; it has never signed in | | `already_member` | Already in this organization | | `other_organization` | Has another home organization; add them with `external: true` | | `personal_plan` | Pays for a personal plan | | `contained` | Their home organization has `members_can_join_other_organizations` off | Pending invites of the people added are revoked. Move a workspace out [#move-a-workspace-out] `DELETE /api/v1/platform-admin/spaces/{slug}/organization/` takes a workspace out of its organization. Holders and pending invites of the organization's custom roles get `member`, the workspace's custom roles are deleted, and nobody is removed; the workspace's own role changes keep applying. `404` for an unknown workspace, `409` when it is in no organization. `POST …/organization/move-out-preview/` returns, without moving anything, each role's gained and lost permissions and the people and invites `reassigned` to `member`. Delete [#delete] | Organization | Result | | ----------------- | ------------------------------------------------------------------------------------------------------- | | No live paid plan | Retired now: `{"status": "deleted"}` | | Live paid plan | Ends with the billing period: `{"status": "scheduled", "ends_at"}`; members keep their seats until then | Retiring keeps the records and removes everyone's membership. The workspaces keep the organization's last role settings.