Service: SuperTokens - EyevinnOSC/community GitHub Wiki

SuperTokens

SuperTokens core (serviceId supertokens-supertokens-core, catalog page) is the core service of the open source SuperTokens authentication solution: login, session management and multi-factor authentication with no vendor lock-in. It exposes a REST API on port 3567 that your backend (through a SuperTokens SDK) calls. It is a long-running service instance.

What it can do

  • Provide login, session management and multi-factor authentication for your applications.
  • Store users, sessions and authentication state in PostgreSQL.
  • Be used from backends through SDKs for Node.js, Python, Go and other languages.

Creating an instance

SuperTokens needs a PostgreSQL database. Create it first and confirm it is running.

  1. Create PostgreSQL (serviceId birme-osc-postgresql, see PostgreSQL) with create-service-instance, config { "name": "authdb", "PostgresPassword": "{{secrets.pgpwd}}", "PostgresDb": "supertokens" } (create the secret first with create-service-secret). PostgresDb is documented to set the default database created at start; the previous version of this page noted that you may otherwise need to run CREATE DATABASE supertokens; yourself. Read host and port with describe-service-instance.
  2. Store the connection string as a secret named dburl (create-service-secret, serviceId: "supertokens-supertokens-core"). Format: postgresql://postgres:<password>@<host>:<port>/supertokens.
  3. Store the API key(s) as a secret, e.g. apikeys. Each key must be at least 20 characters and may contain only letters, digits, = and -; several keys are comma separated (SuperTokens config).
  4. Create the core:
{
  "name": "myauth",
  "databaseUrl": "{{secrets.dburl}}",
  "apiKeys": "{{secrets.apikeys}}"
}
  1. Verify with wait-for-service-ready or get-instance-status, then check the /hello endpoint, which returns Hello:
curl https://<tenant>-myauth.supertokens-supertokens-core.auto.prod-se.osaas.io/hello

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
bulkMigrationCronEnabled No boolean Enables or disables the bulk migration cron job that handles periodic data migration tasks in the core.
databaseUrl Yes string, sensitive Database connection URL the core uses to store authentication data and sessions. PostgreSQL, format postgresql://<user>:<password>@<host>:<port>/<database>. The catalog links it to the TCP address of a birme-osc-postgresql instance. Keep it in a secret.
apiKeys Yes string, sensitive API key(s) required to query the core. Comma separated key1,key2; each key at least 20 characters, only letters, digits, = and -. Your backend must send the key to the core (the SDK apiKey setting). Keep it in a secret.

{{secrets.NAME}} must be the entire field value. Overwriting a secret does not restart a running instance; use restart-service-instance afterwards.

PostgreSQL options (birme-osc-postgresql)

Option Required Type Meaning
name Yes string Instance name.
PostgresPassword Yes string, sensitive Password of the PostgreSQL superuser.
PostgresUser No string Superuser name. Defaults to postgres.
PostgresDb No string Default database to create at start. Defaults to the same name as the user.
PostgresInitDbArgs No string Extra arguments passed to initdb.
PostgresInitDbSql No string SQL commands or script content run at initialization.

Using the instance

Initialize the SDK in your backend with the core URL (and the API key from apiKeys):

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-se.osaas.io',
    apiKey: '<one of the keys in apiKeys>',
  },
  appInfo: {
    appName: 'My App',
    apiDomain: 'https://api.example.com',
    websiteDomain: 'https://example.com',
  },
  recipeList: [EmailPassword.init(), Session.init()],
});

Example with the OSC CLI:

osc create supertokens-supertokens-core myauth \
  -o databaseUrl="{{secrets.dburl}}" \
  -o apiKeys="{{secrets.apikeys}}"

Note that OSC puts an authentication gate in front of instance URLs except / unless the service defines public paths, so check access from your backend to the core after creating it.

Resources

⚠️ **GitHub.com Fallback** ⚠️