Self-host SuperTokens

Run SuperTokens on your infrastructure, control authentication data, and scale as needed.

Overview

The following tutorial shows you how to self-host legacy SuperTokens Core 10.x. Since version 11.0.0, SuperTokens Core no longer supports MySQL as a database.

Before you start

To deploy the Core Service you must configure two things: the actual API and the database.

You can use either PostgreSQL or MySQL as a data source for the Core service.
Deploy the core service with Docker or directly inside your VM.
The archived guide recommended MySQL 8.0.11 and PostgreSQL 13.0. Released source does not establish these as exact lower bounds; verify the database version against your selected Core 10.x and database-plugin release.

Steps

1. Install SuperTokens core

With Docker

docker run -p 127.0.0.1:3567:3567 -d supertokens/supertokens-mysql:10.1

docker run -p 127.0.0.1:3567:3567 -d supertokens/supertokens-postgresql:10.1

The above command starts the container with an in-memory database. This means you do not need to connect it to MySQL to test out SuperTokens.

The above command starts the container with an in-memory database. This means you do not need to connect it to PostgreSQL to test out SuperTokens.

Without Docker

1. Download SuperTokens

Visit the open source download page

Open the open source download page.

Click on the Binary tab

Choose your database

Download the SuperTokens zip file for your OS

After downloading, verify the release checksum or signature and extract the archive. You should see a folder named supertokens.

2. Install SuperTokens

# sudo is required so that the supertokens
# command can be added to your PATH variable.

cd supertokens
sudo ./install


cd supertokens
./install


Rem run as an Administrator. This is required so that the supertokens
Rem command can be added to your PATH.

cd supertokens
install.bat

3. Start the core service

Running the following command starts the service.

supertokens start [--host=...] [--port=...]

The above command starts the Core process using the configured database.
To see all available options please run supertokens start --help

2. Test that the service is running

Open a browser and visit http://localhost:3567/hello. If you see a page that says Hello back, then the container started successfully!

If you are having issues with starting the docker image, please feel free to reach out over email or via Discord.

3. Connect the backend SDK with SuperTokens

The default port is 3567. Keep it private. For local testing, bind it only to 127.0.0.1, for example -p 127.0.0.1:8080:3567.
The connection info goes in the supertokens object in the init function on your backend:

import supertokens from "supertokens-node";

const apiKey = process.env.SUPERTOKENS_API_KEY;
if (apiKey === undefined || apiKey.length === 0) {
  throw new Error("SUPERTOKENS_API_KEY is required");
}

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

import (
	"os"

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

func main() {
	apiKey := os.Getenv("SUPERTOKENS_API_KEY")
	if apiKey == "" {
		panic("SUPERTOKENS_API_KEY is required")
	}
	supertokens.Init(supertokens.TypeInput{
		Supertokens: &supertokens.ConnectionInfo{
			ConnectionURI: "http://localhost:3567",
			APIKey:        apiKey,
		},
	})
}

import os

from supertokens_python import init, InputAppInfo, SupertokensConfig

api_key = os.environ["SUPERTOKENS_API_KEY"]
if not api_key:
    raise RuntimeError("SUPERTOKENS_API_KEY is required")

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

4. Set up the database

4.1 Create a database (optional)

CREATE DATABASE SuperTokens;

CREATE DATABASE supertokens;

You can skip this step if you want SuperTokens to write to your own database. In this case, you need to provide your database’s name as shown in the step below.

4.2 Connect SuperTokens to your database

With Docker


: "${SUPERTOKENS_API_KEY:?Set a generated Core API key}"
docker run \
    --network app-network \
    -e MYSQL_CONNECTION_URI="mysql://username:pass@host/dbName" \
    -e API_KEYS="$SUPERTOKENS_API_KEY" \
    -d supertokens/supertokens-mysql:10.1

# OR

docker run \
    --network app-network \
    -e MYSQL_USER="username" \
    -e MYSQL_PASSWORD="password" \
	-e MYSQL_HOST="host" \
	-e MYSQL_PORT="3306" \
    -e MYSQL_DATABASE_NAME="supertokens" \
    -e API_KEYS="$SUPERTOKENS_API_KEY" \
    -d supertokens/supertokens-mysql:10.1


: "${SUPERTOKENS_API_KEY:?Set a generated Core API key}"
docker run \
    --network app-network \
    -e POSTGRESQL_CONNECTION_URI="postgresql://username:pass@host/dbName" \
    -e API_KEYS="$SUPERTOKENS_API_KEY" \
    -d supertokens/supertokens-postgresql:10.1

# OR

docker run \
    --network app-network \
    -e POSTGRESQL_USER="username" \
    -e POSTGRESQL_PASSWORD="password" \
	-e POSTGRESQL_HOST="host" \
	-e POSTGRESQL_PORT="5432" \
    -e POSTGRESQL_DATABASE_NAME="supertokens" \
    -e API_KEYS="$SUPERTOKENS_API_KEY" \
    -d supertokens/supertokens-postgresql:10.1

Without Docker

# You need to add the following to the config.yaml file.
# The file path can be found by running the "supertokens --help" command

mysql_connection_uri: "mysql://username:pass@host/dbName"

# OR

mysql_user: "username"

mysql_password: "password"

mysql_host: "host"

mysql_port: 3306

mysql_database_name: "supertokens"

# You need to add the following to the config.yaml file.
# The file path can be found by running the "supertokens --help" command

postgresql_connection_uri: "postgresql://username:pass@host/dbName"

# OR

postgresql_user: "username"

postgresql_password: "password"

postgresql_host: "host"

postgresql_port: "5432"

postgresql_database_name: "supertokens"

You can also provide the table schema by setting the postgresql_table_schema option.

Start the exact Core 10.x release against a staging copy of the database and require startup/migration success. Then exercise an authenticated SDK operation. Querying one table does not prove that all release-matched migrations exist.

4.4 Rename database tables (optional)

You can add a prefix to all table names that SuperTokens manages. This way, all will be renamed in a way that has no clashes with your tables.

For example, two tables created by SuperTokens have the names emailpassword_users and thirdparty_users. If you add a prefix to them (something like "my_prefix"), then the tables become my_prefix_emailpassword_users and my_prefix_thirdparty_users.

For MySQL

docker run \
    --network app-network \
    -e MYSQL_TABLE_NAMES_PREFIX="my_prefix" \
    -e API_KEYS="$SUPERTOKENS_API_KEY" \
    -d supertokens/supertokens-mysql:10.1

# You need to add the following to the config.yaml file.
# The file path can be found by running the "supertokens --help" command

mysql_table_names_prefix: "my_prefix"

For PostgreSQL

docker run \
    --network app-network \
    -e POSTGRESQL_TABLE_NAMES_PREFIX="my_prefix" \
    -e API_KEYS="$SUPERTOKENS_API_KEY" \
    -d supertokens/supertokens-postgresql:10.1

# You need to add the following to the config.yaml file.
# The file path can be found by running the "supertokens --help" command

postgresql_table_names_prefix: "my_prefix"

5. Add license keys

Some Core v10 enterprise features require a license key. Confirm with SuperTokens that your plan and key apply to the exact legacy release; this archived page does not establish the current acquisition process.

Once you have the license key you need to manually add it to your SuperTokens Core Instance. To do this you have to call the Core API with the following request:

curl --location --request PUT "${CORE_API_ENDPOINT:?Set the private Core endpoint}/ee/license" \
     --header 'Content-Type: application/json' \
     --header "api-key: ${SUPERTOKENS_API_KEY:?Set the Core API key}" \
     --data-raw "{ \"licenseKey\": \"${SUPERTOKENS_LICENSE_KEY:?Set the license key}\" }"

Select immutable legacy artifacts

The Core images on this page are pinned to the released v10.1 image line so that Docker does not silently select a newer Core major. For a production archive, resolve those tags to registry digests and record repository:10.1@sha256:<digest> in deployment configuration. Pin the database image by digest from a version supported by your verified Core v10/database-plugin tuple, scan all images, and promote unchanged digests between environments.

The archived guide does not establish an immutable MySQL/PostgreSQL image mapping or a maintained Helm-chart release. Consequently, the old mutable Compose examples and deprecated Helm links have been removed. Confirm the database support matrix and exact artifacts before treating this legacy guide as a reproducible production deployment.

Self-host SuperTokens

Overview

Before you start

Steps

1. Install SuperTokens core

With Docker

Without Docker

1. Download SuperTokens

2. Install SuperTokens

3. Start the core service

2. Test that the service is running

3. Connect the backend SDK with SuperTokens

4. Set up the database

4.1 Create a database (optional)

4.2 Connect SuperTokens to your database

With Docker

Without Docker

4.3 Test the connection

4.4 Rename database tables (optional)

For MySQL

For PostgreSQL

5. Add license keys

Select immutable legacy artifacts

API schema and response details