Multitenancy ("WorkSpaces")


A tenant/workspace is the core model which establishes a hierarchy for linking other apps including payments, 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.

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

Single tenant - Normal Django App

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

  • Single Tenant Created

  • All users belong to the same tenant

  • An example usecase is internal tools for a single organisation

  • Example Internal Marketing Dashboard For a Company

Multitenant app with Single tenant per user

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

  • Only one user per tenant

  • Every user belongs to one tenant

  • Invitation to external users flow disabled

  • Most commonly used by SaaS or B2C products. ExampleSocial App where users will always have an individual account.

Multitenant app with shared tenants/workspaces

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

  • Multiple Users per Tenant

  • Each user can switch between tenants

  • example, your typical SaaS application - a unified messaging SaaS platform.

User Tenant/ Workspace role

Workspace roles are defined in the config/ file. Each user is assigned a role based on when creating or joining a workspace. See the roles and permissions docs for more info. Each tenant is able to manage a user’s role from their own settings dashboard.


Workspaces vs Tenants

Both terms have been used interchangeably throughout this article and in the codebase. Workspaces is primarily a front-end term. You could also opt to call these teams. In future versions, we will clean this up and provide a flag for switching the term.