Initial setup

Create your first tenant and configure authentication on it.

Set up tenant-specific authentication and enterprise providers.

Set up SuperTokens multi-tenancy for this application. Inspect the existing backend, frontend, authentication recipes, and tenant identification strategy. Determine whether the feature requires the managed service, configure tenant creation and enabled first factors, and add enterprise provider configuration with credentials stored in environment variables. Preserve existing conventions, avoid committing secrets, and validate tenant resolution, provider callbacks, login, and session behavior for more than one tenant.

Before you start

This feature is only available to paid users. Follow the instructions below to enable it.

Managed Service

1. Sign in to the SuperTokens dashboard.
2. Select the managed service option from the service type select component.
3. Select your core instance from the next element or create a new one.
4. Open Features sub-page and enable the required ones.

Self Hosted

1. Sign in to the SuperTokens dashboard.
2. Select the self-hosted option from the service type select component.
3. Select your license key from the next element or create a new one. Then enable the required features.
4. If the key is not yet configured, add it to your Core service. If your Core already uses this key, no configuration changes are required.

Steps

1. Create a tenant

The first step in setting up a multi tenant login system is to create a tenant in the SuperTokens core. Each tenant has a unique tenantId mapped to that tenant’s configuration. The tenantId could be that tenant’s subdomain, or a workspace URL, or anything else that can help identify them.

Create a new tenant by clicking on the Add Tenant button and specify the tenant ID.

Once you create the tenant, turn on the Login Methods as required for the tenant.

Language Node.js

import Multitenancy from "supertokens-node/recipe/multitenancy";

async function createNewTenant() {
  let resp = await Multitenancy.createOrUpdateTenant("customer1", {
    firstFactors: ["emailpassword", "thirdparty", "otp-email", "otp-phone", "link-phone", "link-email"],
  });

if (resp.createdNew) {
    // Tenant created successfully
  } else {
    // Existing tenant's config was modified.
  }
}

2. Provide additional configuration per tenant

You can also configure a tenant to use different settings. The next sample shows you how to customize the values.

In the above example, the system assigns different values for certain configurations for customer1 tenant. All other configurations inherit from the base configuration.

import Multitenancy from "supertokens-node/recipe/multitenancy";

async function createNewTenant() {
  let resp = await Multitenancy.createOrUpdateTenant("customer1", {
    coreConfig: {
      email_verification_token_lifetime: 7200000,
      password_reset_token_lifetime: 3600000,
      postgresql_connection_uri: "postgresql://localhost:5432/db2",
    },
  });

if (resp.createdNew) {
    // new tenant was created
  } else {
    // existing tenant's config was modified.
  }
}

3. View tenant details

To view the configuration for a specific tenant you can use an SDK method or call the API directly.

import Multitenancy from "supertokens-node/recipe/multitenancy";

async function getTenant(tenantId: string) {
  let resp = await Multitenancy.getTenant(tenantId);

if (resp === undefined) {
    // tenant does not exist
  } else {
    let coreConfig = resp.coreConfig;
    let firstFactors = resp.firstFactors;
    let configuredThirdPartyProviders = resp.thirdParty.providers;
  }
}

4. Set up the user interface

To allow users to authenticate using one of your previously created tenants you need to update your frontend application. You can do this in two ways: through a common domain or through subdomains. Explore the two guides for a full list of instructions on how to implement the flows.