> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt).

# Organizations and workspaces

Organizations and workspaces [#organizations-and-workspaces]

A workspace is the tenant boundary for data and access; an organization optionally groups workspaces so they share roles.

Hierarchy [#hierarchy]

```text
Platform                one Alomana deployment and its platform admins
└── Organization        optional; members and their organization roles, custom workspace roles, role changes
    └── Workspace       agents, connections, files, settings, members, workspace keys
        └── Member      a user with exactly one role in this workspace
```

A workspace without an organization uses the platform's default roles directly.

What lives where [#what-lives-where]

| Level        | Holds                                                                                                                                         | Managed by                                           |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Platform     | Default roles, platform settings, all organizations and workspaces                                                                            | Platform admins, with a bearer token or platform key |
| Organization | Organization members and invites, organization roles with their workspace limits, custom workspace roles, changes to roles for its workspaces | Organization admins (signed in) and platform admins  |
| Workspace    | Agents, connections, files, settings, members, invites, role changes for this workspace                                                       | Workspace members whose role allows it               |
| User         | Chats, profile                                                                                                                                | The user only; workspace admins get no access        |

Selecting a workspace [#selecting-a-workspace]

Every workspace request names its workspace with `X-Space-Slug`. A workspace key only accepts its own workspace's slug; see [Authentication and API keys](../api-basics/authentication).

Rules [#rules]

* A user has at most one home organization, which pays for them, and can be an external member of others. A home invite accepted with `switch_home: true` moves their home; the old one becomes external. See [Members](../platform/organizations#members).
* While a home organization has `members_can_join_other_organizations` off, the default, its members join only its workspaces: adding, inviting or accepting an invite into any other workspace returns `409` `OUTSIDE_ORGANIZATION`, and external invites elsewhere return `409` `HOME_ORGANIZATION_CONTAINED`.
* Accepting an organization invite moves no workspace and removes no workspace membership. Only the workspaces named in `workspace_slugs` move in.
* `/api/v1/organizations/current/` routes act on the organization of the workspace in `X-Space-Slug` when you are a member of it, else on your home, else on your oldest external membership.
* Organization admins get no automatic access to the organization's workspaces; add them as workspace members.
* A workspace joins an organization when it is created there (`POST /api/v1/spaces/` with `organization_id`, or by a home member, whatever `in_organization` says), when its creator brings it in on accepting an invite, or when a platform admin creates it with `POST /api/v1/platform-admin/spaces/` and `organization_id` or moves it with `PUT /api/v1/platform-admin/spaces/{slug}/organization/`. Only a platform admin moves it out again, with `DELETE` on the same URL.
* An organization must keep at least one admin: `409` `LAST_ORGANIZATION_ADMIN`.
* Deleting an organization ends its memberships; its workspaces keep its last role settings.