Skip to main content

​
Overview

Apps represent separate applications or environments within your SuperTokens instance. Each app contains one or more tenants and can have its own configuration.

​
PUT /recipe/multitenancy/app

Create or update an application.

​
Request Body

{
  "appId": "string (optional)",
  "emailPasswordEnabled": "boolean (optional)",
  "passwordlessEnabled": "boolean (optional)",
  "thirdPartyEnabled": "boolean (optional)",
  "coreConfig": {
    // App-specific core configuration
  }
}

​
Parameters

  • appId (string, optional): Unique identifier for the app. If not provided, defaults to “public”
  • emailPasswordEnabled (boolean, optional): Enable email/password authentication for all tenants in this app
  • passwordlessEnabled (boolean, optional): Enable passwordless authentication for all tenants in this app
  • thirdPartyEnabled (boolean, optional): Enable third-party (social) authentication for all tenants in this app
  • coreConfig (object, optional): App-specific configuration that applies to all tenants

​
Response

{
  "status": "OK",
  "createdNew": "boolean"
}
  • createdNew: true if a new app was created, false if existing app was updated

​
Example

curl -X PUT https://your-api-domain.com/recipe/multitenancy/app \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "production",
    "emailPasswordEnabled": true,
    "thirdPartyEnabled": true,
    "coreConfig": {
      "access_token_validity": 3600
    }
  }'

​
GET /recipe/multitenancy/app/list

List all apps in the current connection URI domain. Note: This endpoint can only be called from the public tenant of the public app.

​
Response

{
  "status": "OK",
  "apps": [
    {
      "appId": "string",
      "tenants": [
        {
          "tenantId": "string",
          "emailPassword": {
            "enabled": "boolean"
          },
          "passwordless": {
            "enabled": "boolean"
          },
          "thirdParty": {
            "enabled": "boolean",
            "providers": []
          },
          "coreConfig": {}
        }
      ]
    }
  ]
}

​
Example

curl -X GET https://your-api-domain.com/recipe/multitenancy/app/list

​
DELETE /recipe/multitenancy/app

Remove an app and all its tenants.

​
Request Body

{
  "appId": "string"
}

​
Response

{
  "status": "OK",
  "didExist": "boolean"
}
  • didExist: true if the app existed and was deleted, false if it didn’t exist

​
Example

curl -X DELETE https://your-api-domain.com/recipe/multitenancy/app \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "staging"
  }'

​
Implementation Details

  • Located in: src/main/java/io/supertokens/webserver/api/multitenancy/CreateOrUpdateAppAPI.java:36 and ListAppsAPI.java:43
  • Recipe: MULTITENANCY
  • App IDs are normalized and validated before use
  • The public app (ID: “public”) is created automatically
  • Each app automatically gets a public tenant on creation
  • Configuration is inherited by tenants within the app
  • Protected configuration values can be hidden based on API key permissions

​
App vs Tenant Configuration

​
App-level Configuration

Configuration set at the app level applies to all tenants within that app:
  • Core settings (token validity, password policy, etc.)
  • Enabled authentication methods
  • Default third-party providers

​
Tenant-level Overrides

Tenants can override app-level configuration:
  • Enable/disable specific authentication methods
  • Configure tenant-specific providers
  • Customize token validity and other settings

​
Use Cases

​
Multiple Environments

Create separate apps for different deployment environments: 
# Production app
curl -X PUT https://your-api-domain.com/recipe/multitenancy/app \
  -d '{"appId": "production"}'

# Staging app
curl -X PUT https://your-api-domain.com/recipe/multitenancy/app \
  -d '{"appId": "staging"}'

# Development app
curl -X PUT https://your-api-domain.com/recipe/multitenancy/app \
  -d '{"appId": "development"}'

​
Multi-product Company

Separate apps for different products: 
# E-commerce app
curl -X PUT https://your-api-domain.com/recipe/multitenancy/app \
  -d '{"appId": "ecommerce", "emailPasswordEnabled": true}'

# Admin portal app
curl -X PUT https://your-api-domain.com/recipe/multitenancy/app \
  -d '{"appId": "admin", "passwordlessEnabled": true}'

​
Permissions

  • Listing apps: Only allowed from the public tenant of the public app
  • Creating/updating apps: Must be done from the public tenant context
  • Deleting apps: The public app cannot be deleted

​
Best Practices

  1. Use descriptive app IDs that indicate purpose (e.g., “production”, “api-v2”)
  2. Configure common settings at the app level to avoid repetition
  3. Keep the number of apps minimal - use tenants for isolation within an app
  4. Document your app structure and intended use
  5. Use separate apps for completely isolated environments (prod/staging)
  6. Back up app configuration before making changes

​
Connection URI Domains

Apps are grouped under connection URI domains. In most deployments, you’ll have a single connection URI domain. For more complex setups:
  • PUT /recipe/multitenancy/connectionuridomain - Create or update a connection URI domain
  • GET /recipe/multitenancy/connectionuridomain/list - List all connection URI domains
  • DELETE /recipe/multitenancy/connectionuridomain - Remove a connection URI domain

Build docs developers (and LLMs) love

Get started for freeTalk to us