Multitenancy (“Workspaces”)


A tenant/workspace is the core model which establishes a hierarchy for linking apps (including payments, teams) and users.


Tenant logic is applied to the data layer. Tenants share the same database and schema. There is a main tenant table, to which all other Tenant-Aware tables must be linked via foreign keys.

Queries are filtered based on the tenant_id for the tenant-aware models. Each tenant model includes a custom manager for filtering the queryset based on the tenant.

  • Important All users must be linked to a tenant. Depending on the configuration (see Tenant Modes below) this can be to more than one tenant.
  • Important For all other tenant aware models, the model must be linked to only one tenant
  • The model should subclass TenantModelMixin which inserts a tenant_id field on the model.
  • The model manager should subclass the TenantModelManagerMixin
  • The standard objects manager must be replaced with the new custom manager.

Please note that this is distinct from the Teams feature.

Tenant Modes

An app can be in one of three TenantModes:

The tenant mode must be set up during configuration but can be changed from config/settings/mixins/ .

  1. SINGLE_TENANT - All users belong to the same tenant. i.e. One workspace for all tenants.

  2. Single Tenant Created

  3. All users belong to the same tenant
  4. Teams features enabled
  5. An example usecase is internal tools for a single organisation
  6. Example Internal Marketing Dashboard For a Company

  7. SINGLE_TENANT_PER_USER - User belongs to one tenant. Tenant/Workspace cannot have more than one user.

  8. Only one user per tenant

  9. Every user belongs to one tenant
  10. Invitation to external users flow disabled
  11. Teams feature is also disabled
  12. Most commonly used by SaaS or B2C products. ExampleSocial App where users will always have an individual account.

  13. MULTI_TENANT_PER_USER - User belongs to multiple tenants/workspaces. Each tenant/workspace can have multiple users

  14. Multiple Users per Tenant

  15. Each user can switch between tenants
  16. example, your typical SaaS application - a unified messaging SaaS platform.

User Tenant roles

Each user is assigned one of the following roles:

ROLE_MEMBER = "member"
ROLE_MANAGER = "manager"
ROLE_OWNER = "owner" - assigned to a single user, the owner of the workspace.

Tenant roles for managers and members can be changed by owners directly from the dashboard.

← Users