Manage apps

Create and manage multiple apps within a SuperTokens integration.

Run multiple apps using the same SuperTokens core

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 operates in isolation and can have multiple tenants.
Each app can have its own database or share a database with another app (and yet remain logically isolated).
Each app can have its own set of core and db configurations. If a specific configuration is not explicitly set for an app, it inherits from the base configuration.yaml / docker environment variables configuration.
The core and db configurations of each tenant within an app inherit from the configurations of that app.

You can use this feature to deploy one SuperTokens core across multiple independent apps within your company. Additionally, you can create multiple development environments (dev, staging, prod, etc.) for one app without deploying individual SuperTokens core instances.

1. Create a new app in the core

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

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

The above command creates (or updates) an app with the appId of app1.
It also creates a default tenant for this app with the tenant ID of public (that is, the default tenantId).
You can set core configurations for this app (see the configuration.yaml / docker environment variable options for your core). The core configurations for a new app inherit from the configurations provided in the configuration.yaml / docker environment (or the Configuration page for the managed deployment).
By default, all the login methods enable 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 you can use 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 '<CORE_API_ENDPOINT>/recipe/multitenancy/app' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "app1",
    "thirdPartyEnabled": true,
    "passwordlessEnabled": true,
    "emailPasswordEnabled": true,
    "coreConfig": {...}
}'

The above command creates (or updates) an app with the appId of app1.
It also creates a default tenant for this app with the tenant ID of public (that is, the default tenantId).
You can set core configurations for this app (see the configuration.yaml / docker environment variable options for your core). The core configurations for a new app inherit from the configurations provided in the configuration.yaml / docker environment (or the Configuration page for the managed deployment).
By default, all the login methods enable 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.

2. Configure the `appId` during backend SDK init

Whilst one core can have multiple apps, you must use a dedicated backend (integrated with the 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). The other app’s backend should 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:

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, the backend SDK receives information 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 the SuperTokens core to reliably detect the app that the query is for.

List all the apps in a SuperTokens core

You can only perform this via a cURL command. No helper function exists for this in the backend SDKs since the backend SDKs are per app anyway.

curl --location --request GET '<CORE_API_ENDPOINT>/recipe/multitenancy/app/list/v2' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json'

You get the following JSON output:

{
    "status": "OK",
    "apps": [{
        "appId": "app1",
        "tenants": [{
            "tenantId": "customer1",
            "thirdParty": {
                "providers": [...]
            },
            "coreConfig": {...},
            "firstFactors": [...]
        }]
    }]
}

curl --location --request GET '<CORE_API_ENDPOINT>/recipe/multitenancy/app/list' \
--header 'api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json'