SuperTokens

Last reviewed Aug 26, 2026 · 796 words

SuperTokens is authentication for an application you are writing, not a login wall for applications you are hosting. If the goal is one sign-in in front of Jellyfin, Grafana and the rest of a homelab, stop here and read the Authentik and Authelia comparison; those tools do that job and SuperTokens does not try to. If you are building a web app and would otherwise be reaching for Auth0 or Firebase Auth, SuperTokens is the open-source option with the most complete free tier, and the self-hosted core runs in a 512 MB container on Postgres.

Three pieces, and only one of them is a server

The core is a Java service that owns users, password hashes, sessions and tokens, and exposes an HTTP API on port 3567. It is the part you host and the part with 15,279 GitHub stars. Your application talks to it through a backend SDK, available for Node, Python and Go, which mounts the login and session endpoints on your own API server, and the frontend SDK, for React, vanilla JS and mobile, calls those endpoints and manages tokens in the browser. The browser never talks to the core directly. That design is why it slots into an existing app in an afternoon and also why it is useless as a general-purpose identity provider for other people's software.

The core in Docker with Postgres

services:
  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-postgresql
    ports:
      - "3567:3567"
    environment:
      POSTGRESQL_CONNECTION_URI: "postgresql://supertokens:secret@db:5432/supertokens"
      API_KEYS: "a-long-random-string"
    depends_on: [db]
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: supertokens
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: supertokens
    volumes:
      - ./pg:/var/lib/postgresql/data

Set API_KEYS; without it anyone who can reach port 3567 can create users. Never expose 3567 beyond the network your backend lives on, because the core trusts its callers by design. The backend SDK is then configured with the core's URL and the same API key, and the recipes you enable, such as email-password, passwordless with magic links or OTP, and third-party sign-in with Google, GitHub or Apple, determine which endpoints appear on your API. A MySQL variant of the image exists too, but Postgres is what the project tests hardest.

Session handling is the part worth adopting it for

Most people pick SuperTokens for the login form and stay for the sessions. It issues short-lived access tokens with rotating refresh tokens, detects token theft when an old refresh token is replayed, handles anti-CSRF, and can revoke sessions server-side, which stateless JWT setups usually cannot. The frontend SDK refreshes transparently and the backend SDK gives you a verifySession middleware. Writing this correctly yourself is where home-grown auth goes wrong, and it is the piece that is genuinely hard to get from Keycloak without a lot of adapter code.

Where Keycloak, Zitadel and Ory sit instead

Keycloak is a full OpenID Connect and SAML provider: the right choice when other applications need to authenticate against you, when enterprise SSO via SAML is the requirement, or when you need admin tooling for thousands of users and realms. It also needs 1 GB or more and an operator who knows it. Zitadel is the modern multi-tenant provider in the same space. Ory Kratos is the closest architectural cousin, headless identity with your own UI, and the fairer comparison; SuperTokens wins on prebuilt UI and time to first login, Kratos on flexibility. The identity category lays out the whole field.

What costs money

The core, the SDKs, email-password, passwordless, social login and sessions are free and self-hostable with no user cap. At last check, multi-factor authentication, multi-tenancy and account linking sit behind a license key even when self-hosting, priced per monthly active user. Check the pricing page before you design around MFA, because it is exactly the feature a project adds in month 6 and discovers is not free. Most of what you would pay Auth0 for by user count is free here; the Auth0 alternatives page covers the rest of the field.

What I'd do

For an app I am building with a React or Next.js front end and a Node or Python backend: SuperTokens core in Docker next to the app's Postgres, API_KEYS set, port 3567 on an internal network only, email-password plus one social provider, and the prebuilt UI until the product needs a custom one. For anything that must issue tokens to third-party applications, Keycloak. For the homelab login wall, Authentik. Do not try to bend any of the three into the other's job; the pain is precisely proportional to the mismatch.