Organizations API

These endpoints manage any organization and need a platform admin's bearer token or platform key; org_id is a UUID.

For a step-by-step setup, see Set up a client.

Endpoints

Edit fields

PATCH changes only the fields you send.

An empty string clears an address field.

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

{
  "start_pages": {
    "default": "chat",
    "organization_roles": { "intern": "overview" },
    "workspace_roles": { "member": "overview" }
  }
}

• 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

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.

• 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

• 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.
• A custom role still held by a member or a pending invite cannot be deleted: 409.
• Built-in roles cannot be deleted: 409.

Members

Organization members are separate from workspace members; add people to each workspace with Members and invites.

A person has at most one home organization and can be an external member of others:

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.

The same rules apply to admin_email when an organization is created.

Organization invites expire after 7 days by default; a new invite to the same email revokes the earlier pending one.

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:

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

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

Pending invites of the people added are revoked.

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

Retiring keeps the records and removes everyone's membership. The workspaces keep the organization's last role settings.