Service: SuperTokens - EyevinnOSC/community GitHub Wiki
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.
- 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.
SuperTokens needs a PostgreSQL database. Create it first and confirm it is running.
- Create PostgreSQL (serviceId
birme-osc-postgresql, see PostgreSQL) withcreate-service-instance, config{ "name": "authdb", "PostgresPassword": "{{secrets.pgpwd}}", "PostgresDb": "supertokens" }(create the secret first withcreate-service-secret).PostgresDbis documented to set the default database created at start; the previous version of this page noted that you may otherwise need to runCREATE DATABASE supertokens;yourself. Read host and port withdescribe-service-instance. - Store the connection string as a secret named
dburl(create-service-secret,serviceId: "supertokens-supertokens-core"). Format:postgresql://postgres:<password>@<host>:<port>/supertokens. - 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). - Create the core:
{
"name": "myauth",
"databaseUrl": "{{secrets.dburl}}",
"apiKeys": "{{secrets.apikeys}}"
}- Verify with
wait-for-service-readyorget-instance-status, then check the/helloendpoint, which returnsHello:
curl https://<tenant>-myauth.supertokens-supertokens-core.auto.prod-se.osaas.io/hello| 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.
| 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. |
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.