Skip to main content
Paid Feature

This is a paid feature. For self hosted users, Sign up to get a license key and follow the instructions sent to you by email. This will start a SuperTokens subscription.

If you are using the development environment of our managed service you can use this feature for free. If you want to enable this feature for the production environment, please email us

Architecture

Tenant and App ID#

In a single tenant system, you have one user pool and one common set of login methods for each of the users. In a multi tenant system, you have one user pool per tenant and can have different login methods for each tenant. These different user pools can be in the same database or different databases.

With SuperTokens, there are two levels of abstractions for multi tenancy:

  • Tenant level: This is the level at which you can have different user pools, login methods and / or databases per tenant. All of these tenants and their users are part of the same application. Users can also be shared across tenants.
  • App level: This is the top most level, and is the level at which you can define multiple apps to run using the same SuperTokens core instance. Each app can have its own set of tenants and users, which can't be shared with other apps. Therefore, this is most suitable for:
    • Running different applications within your company, all using the same SuperTokens core instance.
    • Running different dev envs (dev1, dev2, staging, cicd, prod, etc) for the same application.

When you start the core for the first time, SuperTokens creates an app (appId is "public") and one tenant in it (tenantId is "public"). From there on, both tenants and apps can be created dynamically at runtime by querying the core. When you create a new app, you also get a new tenant (tenantId is `"public""") as part of that app created for you.

Relation to end users and their data#

In a multi app, multi tenant setup:

  • A user can be uniquely recognised by their appId -> userId. This allows the same user to be shared across tenants (if you want that to happen).
  • The identity of the user (their email for example) can be uniquely identified by appId -> tenantId -> email. This allows the same email to be used across tenants in a way that they are still treated as different users (they will have different user IDs). The same holds true for phone numbers and third party login profile
  • Roles and permissions are created on an app level, but their mapping to the users are defined on a tenant level. This means that the same user shared across tenants can have different roles / permissions, depending on the tenant they are currently logged into. It also means that you can share the same role / permission set across tenants.
  • Sessions are per tenant (appId -> tenantId -> session handle) and cannot be shared across tenants.
  • User metadata is per app level since users are also on a per app level.

You can also inspect our database schema to get a better understanding of the data model (find the schema in one of the auth recipes -> pre build UI -> core -> self hosted -> postgresql / mysql).

Relation to database#

From a database point of view, you can create multiple apps and tenants in the same database or in different databases. The only restriction is that for an app, you cannot share a user across tenantA and tenantB if the databases for tenantA and tenantB are different. Putting it another way, a user can only be shared across the tenants if those tenants are using the same database.

Relation to backend and frontend SDK setup#

Unlike tenants, each app will need to have its own SuperTokens backend and SuperTokens frontend SDK setup. This means that for each app configured in the SuperTokens core, you will need to run a separate backend and frontend, just for that app. This in turn fits well with the model described above wherein an app is defined as separate, independent applications or separate dev environments.

For multiple tenants, you can run the same backend and frontend across all tenants of an app. Each request from the frontend will contain a tenantId identifying that tenant to the backend, and once logged in, each session will also contain that user's tenantId.

Diagram representation#

Architecture

  • In the above diagram, we see setup for:
    • Single tenant, single app (top left): This is a simple use case that doesn't require the multi tenant feature.
    • Multi temant single app (top right): This is case wherein you have different customers using the same application, but each customer has their own set of users and login methods (each customer is a unique tenant in SuperTokens).
    • Single tenant, multi app (bottom left): This is a case wherein you have multiple applications running on the same SuperTokens core instance, but each application has just a single user pool. This could be two different apps in your organisation, or two different dev environments for the same app (or some combination of this).
    • Multi tenant, multi app (bottom right): This is a case wherein you have multiple applications running on the same SuperTokens core instance, and each application has its own set of tenants. This could be two different apps in your organisation, or two different dev environments for the same app (or some combination of this).
  • The database layer in the above is shown as a single block for each of the scenarios, but for multi tenant, multi app, you can have multiple databases, one for each app, and / or one for each tenant.
Which UI do you use?
Custom UI
Pre built UI