SuperTokens Core: a self-hosted auth service you run against your own database
Open source alternative to Auth0 / Firebase Auth / AWS Cognito
At a glance
- What is it?
- SuperTokens Core is the Java HTTP service at the centre of the SuperTokens open-core auth stack. It handles sign-up, sign-in, session and user data, and it is meant to be self-hosted next to your own database rather than consumed as a hosted identity provider.
- Who is it for?
- Adopt SuperTokens Core if you want the login logic to live in your own infrastructure, next to a database you already operate, and you accept running a Java HTTP service as part of your stack. Do not adopt it if you want a hosted identity provider with no operational surface, or if you need a feature that the README lists only under the enterprise/SSO heading and you are not prepared to check the pricing page.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 27, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What SuperTokens Core actually is, and who ends up running it
The repository is not a complete auth product on its own. It is the core service: an HTTP service that holds the auth logic and performs the database operations. The README describes three building blocks, and the core is the third. The frontend SDK manages session tokens and renders login widgets. The backend SDK exposes APIs for sign-up, sign-in, sign-out and session refreshing, and it is what your frontend talks to. The core sits behind the backend SDK.
That split matters for who this is for. If you are a backend team that already runs your own Postgres or MySQL, and you want user rows in your own schema rather than in a vendor's tenancy, the core is the piece you deploy. The README frames the project as an open-core alternative to Auth0, AWS Cognito and Firebase Auth, and the stated differentiator is on-premises deployment with your own database.
The second stated differentiator is granularity. The README says features are meant to be decoupled, so you can use SuperTokens for just login, for just session management, or for both. It also says session management integrations exist for other login providers, including Auth0. That is an unusual position: the project is willing to sit underneath a competitor's identity layer rather than only replacing it.
The three-tier data flow, and why session checks usually skip the core
Requests move in one direction: browser to your backend, backend to the core, core to your database. The frontend SDK never calls the core directly in the documented architecture. It calls your backend, and your backend SDK calls the core over HTTP.
The design decision worth understanding is where session verification happens. The README states that the most frequent auth operation, session verification, happens inside the backend SDK (Node, Python, Go) without contacting the Java core. Only the operations that need persistence or shared state reach the core. This is what makes the Java memory footprint a smaller problem than it first looks: the README argues a single instance of the core can handle several tens of thousands of users fairly easily, precisely because the hot path is not hitting it.
Two other choices are visible in the repository layout. There is a separate `ee/` directory alongside `src/`, which matches the open-core framing: some functionality is not in the open source tree. There is also a `pluginInterfaceSupported.json` and a `coreDriverInterfaceSupported.json` at the top level, which suggests the core exposes versioned interfaces that SDKs negotiate against. If you build your own client instead of using an official SDK, those files are the compatibility contract you would need to track.
The README also answers the obvious objection to a Java service directly. It lists an embedded Tomcat server instead of a higher-level web framework, careful dependency selection, and a stated future plan to use GraalVM, which the README claims could reduce memory usage by 95 percent. That is a plan, not a shipped property. Treat the memory argument as resting on the session-verification design, not on GraalVM.
Installing SuperTokens Core and pointing a backend SDK at it
The README does not contain step-by-step install instructions. It links to the documentation site and to a guides page, and the repository ships an `install` script, an `install.bat`, a `downloader/` directory and a `cli/` directory at the top level. The Docker badge in the README points at the `supertokens/supertokens-postgresql` image, so the container route is the one the project advertises most visibly.
The README does not give the full run command, the configuration keys or the port the core listens on, so read the documentation site before starting the container. What the repository does show is where the pieces live: `config.yaml` and `devConfig.yaml` at the top level hold configuration, and `cli/` holds the command-line tooling.
docker pull supertokens/supertokens-postgresqlThat is the image name the README's Docker badge references. Everything past the pull, including how the core is told where your database is, is documented on the project site rather than in this repository.
On the application side, the README states that the backend SDK provides the APIs your frontend calls, and that the frontend SDK manages session tokens and renders the login UI widgets. The README lists the supported languages and frameworks as Node.js, Go, Python, React.js, React Native and Vanilla JS, among others, with a link to the full SDK list. The recipes the README names are passwordless login, social login, email password login, phone password login, session management, multi-factor authentication, multi-tenancy and organization support for enterprise SSO, user roles, and microservice authentication.
If you prefer not to use Docker, the README's "Why Java?" section states that the JDK is bundled with the binary and the Docker image, so running the core is meant to feel like running any other HTTP microservice rather than like operating a JVM application. The repository also documents building from source, which is the path to take if you need to patch the core itself.
Where SuperTokens Core is the wrong tool
The clearest limitation is stated by the project itself, in the section explaining the Java choice: if you need to modify the auth APIs, those changes happen at the backend SDK level, not in this repository. The README says you would rarely need to work directly with the Java code. That is a convenience if you are happy with the exposed surface, and a wall if you are not. A team that wants to change how a session token is minted, or how a sign-in flow branches, is working in the SDK, not in the core, and the core's behaviour is not yours to reshape without forking it.
The second boundary is the open-core split. The `ee/` directory exists next to `src/`, and the README's feature list puts multi-tenancy and organization support for enterprise SSO under a heading that also carries the word Enterprise. The README points at the pricing page for the full feature list. If enterprise SSO is a requirement, the open source repository is not where you confirm it is free.
The third is operational. Self-hosting means you now run an HTTP service and a database, and you own the upgrade path. The repository ships `migration_scripts/` and a `SCHEMA-REWORK.md` file, which tells you schema changes happen and are handled by migrations you would be running. The README does not document rollback. A team without anyone willing to own a stateful service should not pick this over a hosted provider, and the README's own framing, that the alternative is hand-rolling auth, is the comparison to make.
Finally, the licence field on the repository is NOASSERTION, and the README links to a `LICENSE.md`. Whatever the terms turn out to be, they are not summarised in the README, so anyone redistributing the core needs to read that file rather than assume an OSI licence.
SuperTokens Core versus Keycloak and hosted identity providers
The most natural self-hosted comparison is Keycloak, which the repository's own topics list alongside auth0, aws-cognito and firebase-auth. The difference in approach is where the protocol complexity sits. Keycloak is an OAuth and OpenID Connect identity provider: your applications integrate as OIDC clients, and the standard flows, token formats and discovery documents are the interface. SuperTokens Core is deliberately not that. The README says the project offers an end-to-end solution with login, sign-ups, user and session management "without all the complexities of OAuth protocols".
That is a real trade, not a marketing line. If you already have services that expect OIDC discovery and standard JWT validation, Keycloak fits without adapter work, and SuperTokens Core would require you to use its SDKs or to build against its driver interface. If you do not need OIDC, SuperTokens removes a layer of protocol you would otherwise have to configure and reason about.
The second comparison is against the hosted providers the README names. Auth0, Cognito and Firebase Auth put the user store in the vendor's account and charge on some usage axis. The README's stated position is that SuperTokens can be used free forever with no limit on the number of users, because the users live in your database. The cost moves from a bill to an operational burden. That is the actual decision, and it is the one the README is arguing for.
The third option is worth naming because the README names it: session management on top of another provider. The README states that session management integrations exist with other login providers such as Auth0. So the core is not strictly an either/or against a hosted provider. You can keep the hosted login and take the session layer.
Maintenance, releases and what upgrading costs you
The repository is not archived, and the last push was on 2026-09-21. The most recent releases listed are v12.3.0-canary from 2026-09-09, v12.2.0 from 2026-09-04 and v12.1.1 from 2026-08-13. The cadence is frequent, and the presence of a canary tag alongside stable tags means there is a pre-release channel you should not point production at.
The upgrade cost is concentrated in two places. First, the core is stateful. The repository contains `migration_scripts/` and a `SCHEMA-REWORK.md`, so version bumps can come with schema changes that must be applied to your database. The README does not document rollback, so the practical safeguard is a database backup before you move a version, not a documented downgrade path.
Second, the versioned interface files at the top level, `coreDriverInterfaceSupported.json` and `pluginInterfaceSupported.json`, are the compatibility surface between the core and whatever talks to it. If you use an official SDK, the SDK release notes are where compatibility is stated. If you have written your own client against the driver interface, those JSON files are what you diff on every core upgrade.
On licence, the repository's licence field is NOASSERTION and the README links to `LICENSE.md`. The open-core structure, with `ee/` separate from `src/`, means the terms for the enterprise functionality may differ from the terms for the core. This is not legal advice; it is a pointer to the two files a legal reviewer would need, and to the fact that the README alone will not answer the question.
Editorial conclusion
Adopt SuperTokens Core if you want the login logic to live in your own infrastructure, next to a database you already operate, and you accept running a Java HTTP service as part of your stack. Do not adopt it if you want a hosted identity provider with no operational surface, or if you need a feature that the README lists only under the enterprise/SSO heading and you are not prepared to check the pricing page. Before committing, verify three things: which database backend your deployment target supports, how the backend SDK you plan to use talks to the core in your network topology, and whether the licence terms in LICENSE.md match how you intend to redistribute the service.
Frequently asked questions
What is SuperTokens Core?
It is the HTTP service that holds the core auth logic and performs database operations for the SuperTokens stack. Backend SDKs call it for sign-up, sign-in, sign-out and session refreshing, while your frontend talks to those backend APIs rather than to the core directly.
Does SuperTokens Core need its own database?
Yes. The README describes the core as performing database operations and frames the project as an on-premises deployment where you control your user data using your own database. The Docker image referenced in the README is the PostgreSQL variant.
Can I run SuperTokens Core with Docker?
The README's Docker badge points at the supertokens/supertokens-postgresql image, and the README states that the JDK ships with the binary and the Docker image so the core runs like any other HTTP microservice. The README itself does not give the full run command, so check the documentation site for the exact flags.
Do I have to modify the Java code to change the auth APIs?
No. The README states that modifications to the auth APIs need to be done at the backend SDK level, such as Node, Go or Python, and that you would rarely need to work directly with the Java code in this repository.
Is SuperTokens Core free with unlimited users?
The README says SuperTokens can be used for free, forever, with no limits on the number of users, and describes the project as open-core. Because the repository has a separate ee/ directory and the README points to the pricing page for the full feature list, confirm the terms for any enterprise feature you need.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/supertokens-supertokens-core)