Organizations & Workspaces

Ragz's tenancy model is a strict three-level hierarchy. Every document, conversation, and permission check is scoped to exactly one place in it.

Organization (tenant)
 └─ Workspace  (= department)
     ├─ Members   (users with a workspace role)
     └─ Documents (folders, ACL groups)

Organization — the tenant boundary. Owns its own users, workspaces, models, quotas, and SSO configuration. Nothing crosses an org boundary; a Postgres query on an org-owned table always goes through TenantContext, and a Qdrant search always carries the caller's org_id. Organizations are managed exclusively by superadmin.
Workspace — a department, team, or project within an org. Workspaces scope documents, retrieval settings (embedding model, chunking, reranking), and membership. A user only sees the workspaces they're a member of.
Members — org users mapped onto a workspace with a workspace role (owner, manager, contributor, viewer — see Roles & Permissions). Owner and manager are the workspace's department admins.
Documents — uploaded into a workspace, optionally into folders, and optionally restricted to one or more ACL groups.

Two different admin surfaces

Org administration (creating organizations, inviting an org's first admin) is a superadmin-only surface: Admin → Organizations. Workspace administration (creating workspaces, managing members) is an admin (or department-admin) surface reached from inside a workspace, not from the platform-wide Admin area.

How a superadmin creates an organization

From Admin → Organizations, New organization opens a form with the org profile:

Field	Notes
Name	Required, unique across the platform.
Contact email	Optional.
Industry	Optional, picked from a fixed list (Technology, Financial Services, Healthcare, …).
Company size	Optional (1–10, 11–50, 51–200, 201–500, 501–1000, 1000+).
Country	Optional, free text.

Organizations can also be edited in place (same fields), and deleted — but delete is safe delete: the platform refuses to delete an organization that still has any users or workspaces (409), and refuses to let a superadmin delete the organization they're currently acting from. An org has to be emptied out — its workspaces and users removed — before it can go away. SSO domains (which email domains may JIT-provision into the org via OIDC) are configured per-org from the same page.

Inviting an admin into an org

Every organization row on Admin → Organizations has an Invite admin shortcut (the person-plus icon). It opens the same invite dialog used elsewhere in the product, pre-seeded with that org selected and the role set to admin — a superadmin doesn't have to separately navigate to a user-management screen and remember to pick the right org and role. The dialog issues a one-time invite link (Ragz has no mailer in this phase; the link is copied and sent out-of-band) that the invitee uses to set their password and land in that org as its admin.

A superadmin can invite into any organization by ID; a plain org admin inviting a new user is hard-scoped to their own org — they never see an org selector at all, and the backend rejects a foreign org_id from anyone below superadmin.

How an admin sets up a workspace

Once an org has an admin, that admin creates the org's departments as workspaces and staffs them:

Create the workspace. Workspaces are created inside the app (not from the platform Admin area) — each one gets its own embedding model, retrieval settings (top-k, min score, reranking), and chunking strategy, independent of every other workspace in the org.
Open workspace settings. The workspace switcher in the sidebar has a settings (gear) icon next to the current workspace — open it to reach the workspace's settings dialog.
Go to the Members tab. The dialog has three tabs: Settings, Members, Evals. Members is where department membership and roles are managed: pick any org user not already a member, assign them a workspace role (owner, manager, contributor, viewer), and add them. Existing members' roles can be changed or the member removed from the same list.

Owner / manager = department admin

A workspace's owner and manager roles are that workspace's department admins — they can manage the workspace's own membership and see its usage/cost reports, without needing org-wide admin. This is how Ragz lets a department run itself day-to-day without every department head needing a platform-level admin account. See Roles & Permissions for exactly what each workspace role can do.

Worked example: new org, new admin, new department

As superadmin, go to Admin → Organizations → New organization. Fill in the name (and profile fields if you have them) and create it.
On that org's row, click Invite admin. The dialog opens pre-scoped to the new org with role admin — fill in the invitee's email, send, and copy the invite link to them.
The invitee opens the link, sets a password, and lands in the new org as its admin.
As that admin, create the org's first workspace (e.g. "Finance").
Open the workspace switcher's gear icon → Members tab, add the people who belong in Finance, and assign one or two of them owner or manager so the department can manage its own membership going forward.
Upload documents into the workspace and, if needed, restrict some of them to an ACL group — see Roles & Permissions for how document-level ACLs interact with workspace membership.