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.

Run multiple apps / dev envs using the same SuperTokens core

Just like how you can create multiple tenants / user pools within one SuperTokens core, you can create multiple apps within one core as well:

Each app is isolated and can have several tenants.
Each app can be assigned its own database, or share a database with another app (and yet be logically isolated).
Each app can have its own set of core and db configs. If a specific config is not explicitly set for an app, it will inherit it from the base config.yaml / docker env vars config.
The core and db configs of each tenant within an app are inherited from the configs of that app.

You can use this feature to use one SuperTokens core deployment across several indepedent apps within your company, and / or to create multiple dev environments (dev, staging, prod etc..) for one app without having to deploy individual SuperTokens core instances.

Create a new / update an app in the core#

caution

This is a paid feature, even if creating an additional dev env on our managed service, or if using our dev licese keys in case of self hosting. The pricing is $50 / month / additional app. Please reach out to use on team@supertokens.com if you have any questions, or if you want to create several envs and want a bulk discount.

In order to create a new app in the SuperTokens core, you can use the following cURL command:

Core version >= 9.1.0
Core version <= 9.0.2

curl --location --request PUT '/recipe/multitenancy/app/v2' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "app1",
    "coreConfig": {...}
}'

The above command will create (or update) an app with the appId of app1.
It will also create a default tenant for this app with the tenant ID of public (i.e. the default tenantId)
You can set various core configs for this app (see the config.yaml / docker env var options for your core). The core configs for a new app will inherit from the the configs provided in the config.yaml / docker env (or our edit config dashboard for managed service).
By default, all the login methods are enabled for a new app (specifically, the public tenant of the new app), but you can pass in firstFactors input to specifically enable selected 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

curl --location --request PUT '/recipe/multitenancy/app' \
--header 'api-key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "app1",
    "thirdPartyEnabled": true,
    "passwordlessEnabled": true,
    "emailPasswordEnabled": true,
    "coreConfig": {...}
}'

The above command will create (or update) an app with the appId of app1.
It will also create a default tenant for this app with the tenant ID of public (i.e. the default tenantId)
You can set various core configs for this app (see the config.yaml / docker env var options for your core). The core configs for a new app will inherit from the the configs provided in the config.yaml / docker env (or our edit config dashboard for managed service).
By default, all the login methods are enabled for a new app (specifically, the public tenant of the new app), but you can pass in false to any of the login methods specified above to disable them.

important

Even if a login method is enabled for a tenant, you will still require to initialise the right recipe on the backend for sign up / in to be possible with that login method. For example, if for a tenant, you have enabled the passwordless login method, but don't use the passwordless (or a combination recipe that has passwordless) on the backend, then end users will not be able to sign up / in using the passwordless APIs cause those APIs won't be exposed via our backend SDK's middleware.

Cofiguring the app ID during backend SDK init#

Whilst one core can have multiple apps, you must use a dedicated backend (integrated with our backend SDK) per app. For example, if you have two apps, and both use a NodeJS backend, then you need to configure one app's backend to have appId as app1 (as an example), and the other app's backend to have appId as app2. You can specify an appId on the backend SDK supertokens.init by appending the appId to the connectionUri as shown below:

NodeJS
GoLang
Python
Other Frameworks

import supertokens from "supertokens-node";

supertokens.init({
    supertokens: {
        connectionURI: "http://localhost:3567/appid-app1",
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: []
});

import "github.com/supertokens/supertokens-golang/supertokens"

func main() {
    supertokens.Init(supertokens.TypeInput{
        Supertokens: &supertokens.ConnectionInfo{
            ConnectionURI: "http://localhost:3567/appid-app1",
        },
    })
}

from supertokens_python import init, InputAppInfo, SupertokensConfig

init(
    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),
    supertokens_config=SupertokensConfig(
        connection_uri='http://localhost:3567/appid-app1',
    ),
    framework='...', 
    recipe_list=[
      #...
   ]
)

In the above code snippet, we tell the backend SDK that the appId to use for this app is app1. You can pick your own app ID, but whatever it is, you need to add it as shown above.
It is important to prefix the app ID with appid- as that enables ths SuperTokens core to reliably detect the app that the query is for.

Auth Methods

Add ons