Multi-tenancy (optional)
By default a Orchestrate install serves one organization. If you run Orchestrate as a service for several organizations, the install can host them all, each isolated from the others.
tenancy.mode | What it is |
|---|---|
single (default) | One organization per install. Nothing on this page applies. |
saas | Many organizations on one install, isolated by PostgreSQL row-level security. |
Switching back to single turns the row-level security off again.
SaaS mode is new and optional. Contact us before you switch an install that holds real data, and try it on a separate install first.
How isolation works
Every row that belongs to an organization carries its organization, and every such table has a row-level security policy. In SaaS mode, the API switches those policies on and forces them at start-up, and every service sets the caller's organization at the start of each database transaction. A row is visible only to its own organization, or to the platform itself.
Who a request acts for comes from its credential:
| Caller | Organization |
|---|---|
| A console user who belongs to one organization | That organization |
| A console user who belongs to several | The one chosen in the console's organization switcher. With none chosen, the request sees nothing. |
| A user whose token names an organization | That organization |
| A platform operator | The whole platform, or one organization when they choose it |
| A personal, project or agent key | The key's organization |
| Hosted chats, channel webhooks and other public routes | The organization of the chat, channel or object the address names |
A request starts bound to nothing, and sees nothing, until its credential binds it. A database connection that never sets an organization sees no rows at all. Shared catalog rows, such as the model catalog, clusters and install-wide policies, are visible to every organization, and only the platform can change them.
Roles
- Platform operator, the realm role
platform-operator(tenancy.operatorRole). Sees every organization, onboards and offboards them, and manages the shared model catalog and install-wide policies. In SaaS mode the platformadminrole on its own no longer reaches every organization: anadminwithout the operator role is an ordinary user, bounded by their organization. - Organization admin, an admin membership on the organization, as on any install. Manages its members, folders, projects, settings, its own custom policies and budgets, and reads its own audit events.
Organization lifecycle
Platform operators manage organizations on Platform in the console.
| Action | What happens |
|---|---|
| Onboard | Creates the organization, its first admin and a first project. With tenancy.keycloakOrganizations, also a Keycloak organization. |
| Suspend and Resume | Refuse, or stop refusing, every member, key and agent of the organization. |
| Offboard | For good: the organization is marked as offboarding and every personal, project and agent key of it is revoked. You must type its id to confirm. |
| Purge | Deletes an offboarding organization's data outside the database, then its rows from every table, then the organization. |
Before any row is deleted, a purge removes the organization's data outside the database: its knowledge bases' vectors and files, its secrets in Vault (connector credentials and users' tokens, channel and webhook secrets, code agent credentials, SIP trunk passwords, its own external models' keys), code agent source archives, build logs and SBOMs, call recordings, and its agent and model images in the registry.
- It is refused while anything of the organization still runs on a cluster, such as a code agent or a model deployment. Undeploy those first.
- It is all or nothing. If a store can't be cleaned, nothing in the database is deleted, and the answer lists the problems. Fix the cause and purge again: every step can be repeated.
- Removing images needs a registry account that can list and delete repositories (
modelRegistry.purgeCredentialsSecret). Without it, the purge leaves the images and names each one it left. - Not removed: model weights an operator imported for the whole install, workflow history (it expires with the orchestration engine's retention), and sign-in accounts, since a person may belong to other organizations.
What each organization owns
- Catalog. Models and clusters can be shared with every organization, or registered for one.
- Custom policies. An organization admin's rules apply only to that organization's projects. Install-wide rules stay with the operators.
- Audit log. Events are filed under the organization, and an organization admin reads only their own.
- Budgets. An organization's budget is set by a platform operator. See Usage controls.
- Settings. Time zone, default guardrail profile, model policy, branding and MFA, set by the organization admin.
Set it up
tenancy:
mode: saas
# keycloakOrganizations: true # needs Keycloak 26 with organizations on the realm
Orchestrate refuses to start in SaaS mode if its database role can bypass row-level security, because isolation would then be a promise and not a control.
Database backups of a SaaS install need the platform scope or a superuser, because a plain connection sees no organization's rows.