Getting Started

SuperTokens is an open-source authentication solution that provides login, session management, and multi-factor authentication for your applications. It exposes a REST API on port 3567 that your backend calls to handle auth logic, with no vendor lock-in. Available as a managed service in Eyevinn Open Source Cloud.

Prerequisites

Step 1: Create a PostgreSQL database

SuperTokens stores user data, sessions, and authentication state in PostgreSQL. Navigate to the PostgreSQL service in the OSC web console, click Create psql-db, and enter a name and password.

Once the instance is running, note the external IP and port. Your connection string will be:

postgresql://postgres:<password>@<IP>:<PORT>/supertokens

Note: You may need to create the supertokens database manually. Connect to the PostgreSQL instance and run CREATE DATABASE supertokens;.

Step 2: Store the database URL as a secret

Navigate to the SuperTokens service page, open the Service Secrets tab, and click New Secret. Name it dburl and paste the connection string as the value.

Step 3: Create a SuperTokens instance

Navigate to the My supertokens-cores tab and click Create supertokens-core. Fill in the fields:

Field Value
Name A short alphanumeric identifier (e.g. myauth)
databaseUrl {{secrets.dburl}}

Click Create and wait for the instance status to turn green.

Step 4: Verify the core is running

Click the instance card to get the URL, then test the /hello endpoint:

curl https://<tenant>-myauth.supertokens-supertokens-core.auto.prod.osaas.io/hello

You should receive a response of Hello.

Step 5: Connect your backend

SuperTokens provides SDKs for Node.js, Python, Go, and other languages. Initialize the SDK in your backend pointing to your SuperTokens core instance:

import supertokens from 'supertokens-node';
import Session from 'supertokens-node/recipe/session';
import EmailPassword from 'supertokens-node/recipe/emailpassword';

supertokens.init({
  framework: 'express',
  supertokens: {
    connectionURI: 'https://<tenant>-myauth.supertokens-supertokens-core.auto.prod.osaas.io',
  },
  appInfo: {
    appName: 'My App',
    apiDomain: 'https://api.example.com',
    websiteDomain: 'https://example.com',
  },
  recipeList: [
    EmailPassword.init(),
    Session.init(),
  ],
});

Configuration Options

Option Required Description
name Yes Alphanumeric instance name
databaseUrl Yes PostgreSQL connection string
bulkMigrationCronEnabled No Enable automated database migration tasks

CLI Usage

# Create a SuperTokens instance
osc create supertokens-supertokens-core myauth \
  -o databaseUrl="{{secrets.dburl}}"

Resources