Which UI do you use?

Custom UI

Pre built UI

Paid Feature

This is a paid feature. Email us to get a license key to start a SuperTokens subscription.

Creating a new tenant

Basic tenant creation

A new tenant can be created for an app using our backend SDK functions or a cURL command as shown below. If an appId is not explicitly specified, the tenant will be created in the "public" appId (the default app that is created when the SuperTokens core first starts).

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

TODO

• We specify the appId for which we want to create a new tenant in the connectionURI of the core during supertokens.init (by providing the /appid-<APP_ID> path in the connectionURI). 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).

Python

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

• We specify the appId for which we want to create a new tenant in the connectionURI of the core during supertokens.init (by providing the /appid-<APP_ID> path in the connectionURI). 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).

cURL

Asyncio

TODO

Syncio

TODO

• We specify the appId for which we want to create a new tenant in the connectionURI of the core during supertokens.init (by providing the /appid-<APP_ID> path in the connectionURI). 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).

curl --location --request PUT '/appid-<APP_ID>/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).

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:

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

TODO

Python

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

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

    resp, err := multitenancy.CreateOrUpdateTenant(&tenantId, multitenancymodels.TenantConfig{
        CoreConfig: map[]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.
    }
}

cURL

Asyncio

TODO

Syncio

TODO

Single tenant setup

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 tenant / app setup

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.

Next steps

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