Which UI do you use?

Custom UI

Pre built UI

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. Creation of tenants is free on the dev license key.

This feature is already enabled for managed service users. Creation of additional tenant is free on the provided development environment.

Creating a new tenant

Dashboard

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

NodeJS

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

• In the above, we are creating a new tenant with the id "customer1". We are also enabling the email password, third party and passwordless login methods for this tenant. You can also disable any of these by not including them in the firstFactors input. If firstFactors is not specified, by default, none of the login methods are enabled.
• You can also set firstFactors to null in which case SDK will be able to use any of the login methods.

The built-in Factor IDs that can be used for firstFactors are:

• Email password auth: emailpassword
• Social login / enterprise SSO auth: thirdparty
• Passwordless:
  • With email OTP: otp-email
  • With SMS OTP: otp-phone
  • With email magic link: link-email
  • With SMS magic link: link-phone

GoLang

import (
    "github.com/supertokens/supertokens-golang/recipe/multitenancy"
    "github.com/supertokens/supertokens-golang/recipe/multitenancy/multitenancymodels"
)

func main() {
    tenantId := "customer1"
    emailPasswordEnabled := true
  thirdPartyEnabled := true
  passwordlessEnabled := true

    resp, err := multitenancy.CreateOrUpdateTenant(tenantId, multitenancymodels.TenantConfig{
        EmailPasswordEnabled: &emailPasswordEnabled,
        ThirdPartyEnabled: &thirdPartyEnabled,
        PasswordlessEnabled: &passwordlessEnabled,
    })

    if err != nil {
        // handle error
    }
    if resp.OK.CreatedNew {
        // new tenant was created
    } else {
        // existing tenant's config was modified.
    }
}

• In the above, we are creating a new tenant with the id "customer1". We are also enabling the email password, third party and passwordless login for this tenant. You can also disable any of these by setting the corresponding field to false (which is also the default setting).

Python

Asyncio

from supertokens_python.recipe.multitenancy.asyncio import create_or_update_tenant
from supertokens_python.recipe.multitenancy.interfaces import TenantConfigCreateOrUpdate

async def some_func():
    response = await create_or_update_tenant("customer1", TenantConfigCreateOrUpdate(
        first_factors=["emailpassword", "thirdparty", "otp-email", "otp-phone", "link-phone", "link-email"]
    ))

    if response.status != "OK":
        print("Handle error")
    elif response.created_new:
        print("New tenant was created")
    else:
        print("Existing tenant's config was updated")

Syncio

from supertokens_python.recipe.multitenancy.syncio import create_or_update_tenant
from supertokens_python.recipe.multitenancy.interfaces import TenantConfigCreateOrUpdate

def some_func():
    response = create_or_update_tenant("customer1", TenantConfigCreateOrUpdate(
        first_factors=["emailpassword", "thirdparty", "otp-email", "otp-phone", "link-phone", "link-email"]
    ))

    if response.status != "OK":
        print("Handle error")
    elif response.created_new:
        print("New tenant was created")
    else:
        print("Existing tenant's config was updated")

• In the above, we are creating a new tenant with the id "customer1". We are also enabling the email password, third party and passwordless login for this tenant. You can also disable any of these by setting the corresponding field to false (which is also the default setting).

cURL

Single app setup

Core version >= 9.1.0

curl --location --request PUT '/recipe/multitenancy/tenant/v2' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "firstFactors": ["emailpassword", "thirdparty", "otp-email", "otp-phone", "link-email", "link-phone"]
}'

• We specify the appId for which we want to create a new tenant in the URL. If you are using the default ("public") app, you can omit the /appid-<APP_ID> part of the URL.
• In the above, we are creating a new tenant with the id "customer1". We are also enabling the email password, third party and passwordless login methods for this tenant. You can also disable any of these by not including them in the firstFactors array. If firstFactors is not specified, by default, none of the login methods will be enabled.
• You can also set firstFactors to null in which case SDK will be able to use any of the login methods.

The built-in Factor IDs that can be used for firstFactors are:

• Email password auth: emailpassword
• Social login / enterprise SSO auth: thirdparty
• Passwordless:
  • With email OTP: otp-email
  • With SMS OTP: otp-phone
  • With email magic link: link-email
  • With SMS magic link: link-phone

Core version <= 9.0.2

curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "emailPasswordEnabled": true,
    "thirdPartyEnabled": true,
    "passwordlessEnabled": true
}'

• We specify the appId for which we want to create a new tenant in the URL. If you are using the default ("public") app, you can omit the /appid-<APP_ID> part of the URL.
• In the above, we are creating a new tenant with the id "customer1". We are also enabling the email password, third party and passwordless login for this tenant. You can also disable any of these by setting the corresponding field to false (which is also the default setting).

Multi app setup

Core version >= 9.1.0

curl --location --request PUT '/recipe/multitenancy/tenant/v2' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "firstFactors": ["emailpassword", "thirdparty", "otp-email", "otp-phone", "link-email", "link-phone"]
}'

• We specify the appId for which we want to create a new tenant in the URL. If you are using the default ("public") app, you can omit the /appid-<APP_ID> part of the URL.
• In the above, we are creating a new tenant with the id "customer1". We are also enabling the email password, third party and passwordless login methods for this tenant. You can also disable any of these by not including them in the firstFactors array. If firstFactors is not specified, by default, none of the login methods will be enabled.
• You can also set firstFactors to null in which case SDK will be able to use any of the login methods.

The built-in Factor IDs that can be used for firstFactors are:

• Email password auth: emailpassword
• Social login / enterprise SSO auth: thirdparty
• Passwordless:
  • With email OTP: otp-email
  • With SMS OTP: otp-phone
  • With email magic link: link-email
  • With SMS magic link: link-phone

Core version <= 9.0.2

curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "emailPasswordEnabled": true,
    "thirdPartyEnabled": true,
    "passwordlessEnabled": true
}'

• We specify the appId for which we want to create a new tenant in the URL. If you are using the default ("public") app, you can omit the /appid-<APP_ID> part of the URL.
• In the above, we are creating a new tenant with the id "customer1". We are also enabling the email password, third party and passwordless login for this tenant. You can also disable any of these by setting the corresponding field to false (which is also the default setting).

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

Once the tenant is created, turn on the Login Methods as required for the tenant. In the above example, all the Login Methods are turned on.

Providing additional configuration per tenant

You can also configure a tenant to have different configurations as per the core's config.yaml (or docker env) variabls. Below is how you can specify the config, when creating or modifying a tenant:

Dashboard

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

NodeJS

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

In the above example, we are setting different values for certain configs for customer1 tenant. All other configs are inherited from the base config (config.yaml file or docker env vars).

We even specify a postgresql_connection_uri config. This means that all the information related to this tenant (users, roles, metadata etc) will be saved in the db pointed to by the value of postgresql_connection_uri (A similar config exists for MySQL as well). This can be used to achieve data isolation on a tenant level. This config is not necessary and if not provided, the tenant's information will be stored in the db as specified in the core's config.yaml or docker env vars (it will still be a different user pool though).

Here is the list of full core config variables that can be configured, and below are the lists of variables depending on the database you use:

• PostgreSQL configs
• MySQL configs

important

Some configs cannot be different across tenants - they must be the same within an app. In the above links, if a config has a comment saying DIFFERENT_ACROSS_TENANTS, then it can be changed for each tenant, else if it has DIFFERENT_ACROSS_APPS, then it must be the same for all tenants within an app.

If a config has neither of these, then it can only be set per core instance.

GoLang

import (
    "github.com/supertokens/supertokens-golang/recipe/multitenancy"
    "github.com/supertokens/supertokens-golang/recipe/multitenancy/multitenancymodels"
)

func main() {
    tenantId := "customer1"

    resp, err := multitenancy.CreateOrUpdateTenant(tenantId, multitenancymodels.TenantConfig{
        CoreConfig: map[string]interface{}{
            "email_verification_token_lifetime": 7200000,
            "password_reset_token_lifetime": 3600000,
            "postgresql_connection_uri": "postgresql://localhost:5432/db2",
        },
    })

    if err != nil {
        // handle error
    }
    if resp.OK.CreatedNew {
        // new tenant was created
    } else {
        // existing tenant's config was modified.
    }
}

In the above example, we are setting different values for certain configs for customer1 tenant. All other configs are inherited from the base config (config.yaml file or docker env vars).

We even specify a postgresql_connection_uri config. This means that all the information related to this tenant (users, roles, metadata etc) will be saved in the db pointed to by the value of postgresql_connection_uri (A similar config exists for MySQL as well). This can be used to achieve data isolation on a tenant level. This config is not necessary and if not provided, the tenant's information will be stored in the db as specified in the core's config.yaml or docker env vars (it will still be a different user pool though).

Here is the list of full core config variables that can be configured, and below are the lists of variables depending on the database you use:

• PostgreSQL configs
• MySQL configs

important

Some configs cannot be different across tenants - they must be the same within an app. In the above links, if a config has a comment saying DIFFERENT_ACROSS_TENANTS, then it can be changed for each tenant, else if it has DIFFERENT_ACROSS_APPS, then it must be the same for all tenants within an app.

If a config has neither of these, then it can only be set per core instance.

Python

Asyncio

from supertokens_python.recipe.multitenancy.asyncio import create_or_update_tenant
from supertokens_python.recipe.multitenancy.interfaces import TenantConfigCreateOrUpdate

async def some_func():
    tenant_id = "customer1"
    result = await create_or_update_tenant(tenant_id, TenantConfigCreateOrUpdate(
        core_config={
            "email_verification_token_lifetime": 7200000,
            "password_reset_token_lifetime": 3600000,
            "postgresql_connection_uri": "postgresql://localhost:5432/db2",
        },
    ))

    if result.status != "OK":
        print("handle error")
    elif result.created_new:
        print("new tenant created")
    else:
        print("existing tenant's config was modified.")

Syncio

from supertokens_python.recipe.multitenancy.syncio import create_or_update_tenant
from supertokens_python.recipe.multitenancy.interfaces import TenantConfigCreateOrUpdate

tenant_id = "customer1"
result = create_or_update_tenant(tenant_id, TenantConfigCreateOrUpdate(
    core_config={
        "email_verification_token_lifetime": 7200000,
        "password_reset_token_lifetime": 3600000,
        "postgresql_connection_uri": "postgresql://localhost:5432/db2",
    },
))

if result.status != "OK":
    print("handle error")
elif result.created_new:
    print("new tenant created")
else:
    print("existing tenant's config was modified.")

In the above example, we are setting different values for certain configs for customer1 tenant. All other configs are inherited from the base config (config.yaml file or docker env vars).

We even specify a postgresql_connection_uri config. This means that all the information related to this tenant (users, roles, metadata etc) will be saved in the db pointed to by the value of postgresql_connection_uri (A similar config exists for MySQL as well). This can be used to achieve data isolation on a tenant level. This config is not necessary and if not provided, the tenant's information will be stored in the db as specified in the core's config.yaml or docker env vars (it will still be a different user pool though).

Here is the list of full core config variables that can be configured, and below are the lists of variables depending on the database you use:

• PostgreSQL configs
• MySQL configs

important

Some configs cannot be different across tenants - they must be the same within an app. In the above links, if a config has a comment saying DIFFERENT_ACROSS_TENANTS, then it can be changed for each tenant, else if it has DIFFERENT_ACROSS_APPS, then it must be the same for all tenants within an app.

If a config has neither of these, then it can only be set per core instance.

cURL

Single app setup

Core version >= 9.1.0

curl --location --request PUT '/recipe/multitenancy/tenant/v2' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "coreConfig": {
        "email_verification_token_lifetime": 7200000,
        "password_reset_token_lifetime": 3600000,
        "postgresql_connection_uri": "postgresql://localhost:5432/db2"
    }   
}'

Core version <= 9.0.2

curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "coreConfig": {
        "email_verification_token_lifetime": 7200000,
        "password_reset_token_lifetime": 3600000,
        "postgresql_connection_uri": "postgresql://localhost:5432/db2"
    }   
}'

Multi app setup

Core version >= 9.1.0

curl --location --request PUT '/recipe/multitenancy/tenant/v2' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "coreConfig": {
        "email_verification_token_lifetime": 7200000,
        "password_reset_token_lifetime": 3600000,
        "postgresql_connection_uri": "postgresql://localhost:5432/db2"
    }   
}'

Core version <= 9.0.2

curl --location --request PUT '/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tenantId": "customer1",
    "coreConfig": {
        "email_verification_token_lifetime": 7200000,
        "password_reset_token_lifetime": 3600000,
        "postgresql_connection_uri": "postgresql://localhost:5432/db2"
    }   
}'

In the above example, we are setting different values for certain configs for customer1 tenant. All other configs are inherited from the base config (config.yaml file or docker env vars).

We even specify a postgresql_connection_uri config. This means that all the information related to this tenant (users, roles, metadata etc) will be saved in the db pointed to by the value of postgresql_connection_uri (A similar config exists for MySQL as well). This can be used to achieve data isolation on a tenant level. This config is not necessary and if not provided, the tenant's information will be stored in the db as specified in the core's config.yaml or docker env vars (it will still be a different user pool though).

Here is the list of full core config variables that can be configured, and below are the lists of variables depending on the database you use:

• PostgreSQL configs
• MySQL configs

important

Some configs cannot be different across tenants - they must be the same within an app. In the above links, if a config has a comment saying DIFFERENT_ACROSS_TENANTS, then it can be changed for each tenant, else if it has DIFFERENT_ACROSS_APPS, then it must be the same for all tenants within an app.

If a config has neither of these, then it can only be set per core instance.

In the above example, we are setting different values for certain configs for customer1 tenant. All other configs are inherited from the base config (config.yaml file or docker env vars).

The values can be edited by clicking on the pencil icon and then specifying a new value.

caution

Database connection settings cannot be edited directly from the Dashboard and you may need to use the SDK or cURL to update them.

Once you have set the configs for a specific tenant, you can fetch the tenant info as shown below:

NodeJS

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

GoLang

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;
    }
}

Python

import (
  "fmt"

    "github.com/supertokens/supertokens-golang/recipe/multitenancy"
)

func main() {
    tenantId := "customer1"

    tenant, err := multitenancy.GetTenant(tenantId)

    if err != nil {
        // handle error
    }
    if tenant == nil {
        // tenant does not exist
    } else {
        isEmailPasswordLoginEnabled := tenant.EmailPassword.Enabled;
        isThirdPartyLoginEnabled := tenant.ThirdParty.Enabled;
        isPasswordlessLoginEnabled := tenant.Passwordless.Enabled;

        if (isEmailPasswordLoginEnabled) {
            // Tenant support email password login
        }
    
        if (isThirdPartyLoginEnabled) {
            // Tenant support third party login
            configuredThirdPartyProviders := tenant.ThirdParty.Providers;
            fmt.Println(configuredThirdPartyProviders);
        }
    
        if (isPasswordlessLoginEnabled) {
            // Tenant support passwordless login
        }
    }
}

cURL

Asyncio

from supertokens_python.recipe.multitenancy.asyncio import get_tenant

async def some_func():
    tenant = await get_tenant("customer1")

    if tenant is None:
        print("tenant does not exist")
    else:
        core_config = tenant.core_config
        first_factors = tenant.first_factors
        providers = tenant.third_party_providers
        
        print(core_config)
        print(first_factors)
        print(providers)

Syncio

from supertokens_python.recipe.multitenancy.syncio import get_tenant

tenant = get_tenant("customer1")

if tenant is None:
    print("tenant does not exist")
else:
    core_config = tenant.core_config
    first_factors = tenant.first_factors
    providers = tenant.third_party_providers
    
    print(core_config)
    print(first_factors)
    print(providers)

Single app setup

Core version >= 9.1.0

curl --location --request GET '/customer1/recipe/multitenancy/tenant/v2' \
--header 'api-key: ' \
--header 'Content-Type: application/json'

Notice that we added customer1 to the path of the request. This tells the core that the tenant you want to get the information about is customer1 (the one we created before in this page).

If the input tenant does not exist, you will get back a 200 status code with the following JSON:

{"status": "TENANT_NOT_FOUND_ERROR"}

Otherwise you will get a 200 status code with the following JSON output:

{
  "status": "OK",
  "thirdParty": {
    "providers": [...]
  },
  "coreConfig": {
    "email_verification_token_lifetime": 7200000,
    "password_reset_token_lifetime": 3600000,
    "postgresql_connection_uri": "postgresql://localhost:5432/db2"
  },
  "tenantId": "customer1",
  "firstFactors": ["emailpassword", "thirdparty", "otp-email", "otp-phone", "link-email", "link-phone"]
}

Core version <= 9.0.2

curl --location --request GET '/customer1/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json'

Notice that we added customer1 to the path of the request. This tells the core that the tenant you want to get the information about is customer1 (the one we created before in this page).

If the input tenant does not exist, you will get back a 200 status code with the following JSON:

{"status": "TENANT_NOT_FOUND_ERROR"}

Otherwise you will get a 200 status code with the following JSON output:

{
  "status": "OK",
  "emailPassword": {
    "enabled": true
  },
  "thirdParty": {
    "enabled": true,
    "providers": [...]
  },
  "passwordless": {
    "enabled": true
  },
  "coreConfig": {
    "email_verification_token_lifetime": 7200000,
    "password_reset_token_lifetime": 3600000,
    "postgresql_connection_uri": "postgresql://localhost:5432/db2"
  },
  "tenantId": "customer1",
}

Multi app setup

Core version >= 9.1.0

curl --location --request GET '/customer1/recipe/multitenancy/tenant/v2' \
--header 'api-key: ' \
--header 'Content-Type: application/json'

Notice that we added customer1 to the path of the request. This tells the core that the tenant you want to get the information about is customer1 (the one we created before in this page).

If the input tenant does not exist, you will get back a 200 status code with the following JSON:

{"status": "TENANT_NOT_FOUND_ERROR"}

Otherwise you will get a 200 status code with the following JSON output:

{
  "status": "OK",
  "thirdParty": {
    "providers": [...]
  },
  "coreConfig": {
    "email_verification_token_lifetime": 7200000,
    "password_reset_token_lifetime": 3600000,
    "postgresql_connection_uri": "postgresql://localhost:5432/db2"
  },
  "tenantId": "customer1",
  "firstFactors": ["emailpassword", "thirdparty", "otp-email", "otp-phone", "link-email", "link-phone"]
}

Core version <= 9.0.2

curl --location --request GET '/customer1/recipe/multitenancy/tenant' \
--header 'api-key: ' \
--header 'Content-Type: application/json'

Notice that we added customer1 to the path of the request. This tells the core that the tenant you want to get the information about is customer1 (the one we created before in this page).

If the input tenant does not exist, you will get back a 200 status code with the following JSON:

{"status": "TENANT_NOT_FOUND_ERROR"}

Otherwise you will get a 200 status code with the following JSON output:

{
  "status": "OK",
  "emailPassword": {
    "enabled": true
  },
  "thirdParty": {
    "enabled": true,
    "providers": [...]
  },
  "passwordless": {
    "enabled": true
  },
  "coreConfig": {
    "email_verification_token_lifetime": 7200000,
    "password_reset_token_lifetime": 3600000,
    "postgresql_connection_uri": "postgresql://localhost:5432/db2"
  },
  "tenantId": "customer1",
}

The returned coreConfig is the same as what we had set when creating / updating the tenant. The rest of the core configurations for this tenant are inherited from the app's (or the public tenant) config. The public tenant, for the public app inherits its configs from the config.yaml / docker env var values.

Next steps

Checkout the "Setting up login for tenants" page for next steps in integrating multi tenancy.