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

caution

This is a paid feature, even if creating an additional dev env on the managed service, or if using the dev license keys in case of self-hosting. The pricing is $50 / month / additional app. Please reach out to support@SuperTokens.com if you have any questions, or if you want to create multiple environments and want a bulk discount.

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 edit configuration dashboard for managed service).
• 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 edit configuration dashboard for managed service).
• 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.

important

Even if a login method enables for a tenant, you still require to initialize 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 cannot sign up / in using the passwordless APIs because those APIs are not exposed via the backend SDK's middleware.

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: []
});

• 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'

You get the following JSON output:

{
    "status": "OK",
    "apps": [{
        "appId": "app1",
        "tenants": [{
            "tenantId": "customer1",
            "emailPassword": {
                "enabled": true
            },
            "thirdParty": {
                "enabled": true,
                "providers": [...]
            },
            "passwordless": {
                "enabled": true
            },
            "coreConfig": {...}
        }]
    }]
}

Delete an app from SuperTokens core

The following snippet shows you how to delete an app from a SuperTokens Core instance. This operation is irreversible and deletes all user data associated with the app.

important

Before you delete an app, ensure that you satisfy the following requirements:

• The request must originate from the public app and tenant
• The app must not have any tenants other than the public tenant. You need to delete other tenants first.

After deleting an app, make sure to update any backend services configured to use this app ID to prevent unexpected errors.

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

• The above command deletes the app with the appId of app1 and all its associated tenants.
• All user data, configuration, and tenant information associated with this app are permanently deleted.
• The API key used must have the necessary permissions to delete apps.

danger

This operation cannot be undone. Make sure you have backed up any important data before proceeding.