SuperTokens

SuperTokens is an open-source authentication and session management platform built as a self-hosted alternative to Auth0, Firebase Auth, and AWS Cognito. Developers get full ownership of their user data — stored in their own database, on their own infrastructure — without the vendor lock-in that comes with managed identity providers.

The platform is structured around a three-layer architecture: frontend SDKs handle UI rendering and token management across React, React Native, Vue, Flutter, and more; backend SDKs expose secure auth APIs for Node.js, Go, and Python; and the Java-based SuperTokens Core manages all authentication logic and database operations as a standalone HTTP microservice.

SuperTokens supports a comprehensive set of auth methods including email/password, passwordless magic links and OTP, social OAuth providers, WebAuthn/passkeys, TOTP-based MFA, and SAML 2.0. Enterprise capabilities like multi-tenancy, account linking, and advanced session management are delivered through a modular feature-flag system that activates at runtime without restarts.

Designed for startups and enterprises alike, SuperTokens can be deployed via Docker or as a standalone binary, integrates with PostgreSQL, MySQL, and MongoDB through a pluggable storage interface, and provides a web-based user management dashboard for admin operations without writing custom tooling.

What You Get

• Passwordless Login - Enables secure login via email magic links or SMS OTP codes without requiring users to manage passwords, reducing phishing risk and friction at sign-up.
• Social and OAuth Login - Pre-built integrations with Google, GitHub, Facebook, Apple, and dozens of other OAuth 2.0 providers with customizable UI components and a consistent token model.
• Email-Password Login - Credential-based authentication with configurable password policies, bcrypt hashing, and built-in reset flows including email verification.
• WebAuthn / Passkey Support - Native passkey authentication using the WebAuthn4J library, allowing users to log in with biometrics or hardware security keys without passwords.
• Session Management - Automatic token refresh, rotating refresh tokens, multi-device session tracking, and the ability to force-logout sessions from other devices.
• Multi-Factor Authentication (MFA) - Layered second-factor verification using TOTP (compatible with Authy/Google Authenticator) or email/SMS OTP, gated as an enterprise feature.
• Multi-Tenancy and Organization Support - Tenant-scoped resource isolation within a single core instance, enabling B2B SaaS products to serve multiple organizations with separate user pools and SSO configuration.
• SAML 2.0 Integration - Built-in OpenSAML-based SAML support for connecting enterprise identity providers like Okta, Azure AD, and OneLogin without external SAML middleware.
• OAuth 2.0 Provider Mode - SuperTokens can act as an OAuth 2.0 authorization server, issuing tokens for third-party clients and enabling SSO across your own product suite.
• User Management Dashboard - Browser-based admin UI for listing users, viewing session data, modifying metadata, managing roles, banning accounts, and resetting passwords without writing code.
• Account Linking - Allows users with the same email to link multiple login methods (e.g., Google + email/password) into a single unified account, managed transactionally.
• Bulk User Import - Supports importing large user batches via a background job with transactional safety and usage enforcement, useful for migrating from other auth providers.

Common Use Cases

• Migrating off Auth0 or Firebase Auth - A team tired of per-user pricing replaces their managed auth provider with SuperTokens, importing existing users and retaining all session tokens without forcing re-login.
• B2B SaaS with per-organization SSO - A multi-tenant product uses SuperTokens’ multi-tenancy feature to give each enterprise customer their own SAML or OAuth configuration with isolated user pools.
• Consumer app with passwordless onboarding - A mobile fintech app implements email or SMS magic link login via SuperTokens to reduce sign-up friction and eliminate password support burden.
• Microservice authentication layer - A backend team uses SuperTokens’ backend SDKs to validate session tokens across Node.js, Go, and Python services without routing every request through a central auth service.
• Adding WebAuthn/passkeys to an existing app - A security-conscious team integrates SuperTokens’ WebAuthn support to offer biometric login on supported devices alongside existing email login.
• Internal tooling with dashboard-based user management - A small team uses the SuperTokens user management dashboard to handle user administration tasks without building custom admin screens.

Under The Hood

Architecture SuperTokens Core is organized around a recipe-based architecture where each authentication method — email-password, passwordless, third-party OAuth, WebAuthn, SAML, TOTP, and MFA — is a fully isolated module with its own HTTP route surface, business logic, and storage contract. All modules are bootstrapped through a single Main entrypoint that starts an embedded Tomcat server and uses a ResourceDistributor to bind singleton resources to tenant identifiers, ensuring per-tenant data isolation within a single running instance. Enterprise features such as multi-tenancy, account linking, MFA, OAuth provider mode, and SAML are gated through a FeatureFlag system that loads external EE JARs at runtime, allowing capabilities to be activated without restarts or code redeployment. The plugin interface layer cleanly separates business logic from storage, enabling swappable backends (PostgreSQL, MySQL, MongoDB, SQLite) with no core changes.

Tech Stack The core is built in Java 21 with AspectJ for cross-cutting concerns such as telemetry instrumentation and request lifecycle hooks. Embedded Tomcat 11 serves as the HTTP layer — a deliberate choice to avoid higher-level web framework overhead while retaining a mature, production-grade server. JSON is handled via Gson and Jackson, YAML config via Jackson Dataformat. Password hashing uses jBCrypt, WebAuthn via WebAuthn4J, and SAML 2.0 via OpenSAML 4. Storage abstraction is handled through a plugin interface with built-in SQLite (via sqlite-jdbc) for development and lightweight deployments. Build tooling uses Gradle with explicit dependency version pinning for reproducible builds.

Code Quality The codebase maintains an approximately one-to-one ratio of test files to source files — 377 test classes covering 396 production classes — spanning unit, integration, and full HTTP API scenarios. Tests are organized by feature module and include environment-aware execution, flaky test retry logic, and feature-flag-gated suites that mirror production configurations. Error handling follows a custom exception hierarchy with named types for each failure mode, and the storage abstraction enforces typed contracts so storage errors are caught at compilation rather than runtime. CI runs the full test suite and enforces formatting through Checkstyle.

What Makes It Unique The combination of recipe isolation, runtime EE JAR loading, and tenant-aware resource scoping in a single self-hosted binary is architecturally distinct among open-source auth platforms. Most alternatives either require separate deployments per tenant or lack the per-feature licensing granularity that SuperTokens achieves through its feature-flag JAR system. The decision to proxy OAuth flows through the SuperTokens Core rather than delegating to client-side redirect handling simplifies token management for applications. Native WebAuthn and SAML support without external middleware or SaaS dependencies, combined with an OAuth 2.0 provider mode that can issue tokens for third-party clients, makes SuperTokens viable as both an identity consumer and an identity provider within a single deployment.

Self-Hosting

SuperTokens uses a dual-license model. The core authentication engine outside the ee/ directory is released under the Apache License 2.0, which permits commercial use, modification, and distribution without royalties or copyleft obligations. The contents of the ee/ directory — which include multi-tenancy, account linking, MFA, OAuth provider mode, SAML, and the dashboard login feature — are licensed under a proprietary SuperTokens Enterprise License. You can use and modify EE code freely for development and testing, but production use of EE features requires a paid subscription from SuperTokens Inc. This structure means the free tier is genuinely functional for single-tenant email/password, passwordless, and social login with unlimited users, while advanced organizational and SSO capabilities require a commercial agreement.

Running SuperTokens yourself means operating a Java 21 HTTP microservice alongside your application backend. The core is distributed as a Docker image or a standalone binary bundled with a JDK, so Java installation is not a prerequisite for operators. It persists state to a relational database — PostgreSQL, MySQL, or MongoDB via storage plugins — which you are responsible for provisioning, backing up, and scaling. A single SuperTokens instance handles session verification entirely within backend SDKs without a network call, so it scales well under read-heavy auth patterns, but you are responsible for high-availability setups: running multiple core instances behind a load balancer and configuring your database for replication.

Compared to the managed SuperTokens Cloud offering, self-hosting trades operational simplicity for data sovereignty. The Cloud tier handles uptime, zero-downtime upgrades, automatic backups, and SLA guarantees, while self-hosting places all of that on your team. There is no official SLA for the open-source version. Community support is available through Discord and GitHub Issues, while paid plans include dedicated support channels and access to EE features. If your team lacks the operational capacity to manage database availability and service health for your auth layer, the managed tier or an alternative hosted provider is worth evaluating seriously.