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

Users and tenants

When a user is created, they assigned to the tenantId using which they signed up. This means that that user can only login into that tenant. SuperTokens allows you to assign a user ID to multiple tenants as long as that user's email / phone number is unique for that login method, for each of the new tenants. Once associated with multiple tenants, that user can login to each of the tenants they have been assigned to.

For example, if a user signs up with email password login in the public tenant with email user@example.com, they can be assigned to another tenant (t1 for example), as long as t1 doesn't already have an email password user with the same email (i.e. user@example.com).

In order to associate a user with a tenant, you can call the following API:

import Multitenancy from "supertokens-node/recipe/multitenancy";
import {RecipeUserId} from "supertokens-node";

async function addUserToTenant(recipeUserId: RecipeUserId, tenantId: string) {
let resp = await Multitenancy.associateUserToTenant(tenantId, recipeUserId);

if (resp.status === "OK") {
// User is now associated with tenant
} else if (resp.status === "UNKNOWN_USER_ID_ERROR") {
// The provided user ID was not one that signed up using one of SuperTokens' auth recipes.
} else if (resp.status === "EMAIL_ALREADY_EXISTS_ERROR") {
// This means that the input user is one of passwordless or email password logins, and the new tenant already has a user with the same email for that login method.
} else if (resp.status === "PHONE_NUMBER_ALREADY_EXISTS_ERROR") {
// This means that the input user is a passwordless user and the new tenant already has a user with the same phone number, for passwordless login.
} else if (resp.status === "ASSOCIATION_NOT_ALLOWED_ERROR") {
// This can happen if using account linking along with multi tenancy. One example of when this
// happens if if the target tenant has a primary user with the same email / phone numbers
// as the current user.
} else {
// status is THIRD_PARTY_USER_ALREADY_EXISTS_ERROR
// This means that the input user had already previously signed in with the same third party provider (e.g. Google) for the new tenant.
}
}

You can even remove a user's access from a tenant using the API call shown below. In fact, you can remove a user from all tenants that they have access to, and the user and their metadata will still be in the system, however they will not be able to login into any tenant. To remove a user from a tenant, call the following API:

import Multitenancy from "supertokens-node/recipe/multitenancy";
import {RecipeUserId} from "supertokens-node";

async function removeUserFromTeannt(recipeUserId: RecipeUserId, tenantId: string) {
let resp = await Multitenancy.disassociateUserFromTenant(tenantId, recipeUserId);

if (resp.wasAssociated) {
// User was removed from tenant
} else {
// User was never a part of the tenant anyway
}
}
important
  • Users can only be shared across tenants and not across apps.
  • If your app has two tenants, that are in different database locations, then you cannot share users between them.
Looking for older version of the documentation?
Which UI do you use?
Custom UI
Pre built UI