Organizations and workspaces

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

Hierarchy

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

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.

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