Deploy and Host SuperTokens on Railway

SuperTokens is an open-source authentication service for developers — a self-hosted alternative to Auth0, AWS Cognito, and Okta that adds email/password, social, and passwordless login to your own app via an SDK. Run the Core, integrate a backend SDK, and your app gains sign-up, sign-in, and session management without building auth from scratch or paying per active user. This template deploys the Core wired to PostgreSQL, with the connection-string detail that trips most deployments handled correctly.

What This Template Deploys

Both run on Railway's private network. The Core is stateless — no volume needed, all data lives in Postgres — and communicates with the database over the private network so no credentials touch the public internet.

About Hosting

SuperTokens is straightforward to run once one specific detail is right, and understanding its model helps you use it well.

The database URI must use the postgresql:// scheme — this is the #1 failure. SuperTokens Core requires the connection string to start with postgresql://. If it starts with postgres:// — which is exactly what Railway's default Postgres reference variables often produce — the Core fails to start with an error. This template forces the correct postgresql:// scheme so the Core boots cleanly against Railway's managed Postgres. It's a small detail that causes a lot of failed first deploys, and it's handled here.

SuperTokens is a backend service you integrate, not a standalone login portal. Unlike a full identity-provider UI, it gives you a Core plus an SDK for your language. Install the backend SDK (supertokens-node, supertokens-python[fastapi], or Go), call supertokens.init() with your Railway domain as the connectionURI and the generated API key, and your app gains /auth/signup, /auth/signin, /auth/signout, and session-refresh endpoints automatically. It's built for developers adding auth directly into their own application.

The API key secures the Core. API_KEYS is the credential your backend uses to talk to the Core — generated on deploy, used as the apiKey in your SDK config. Verify the Core is healthy any time by hitting /hello, which returns Hello when the database connection works.

Postgres only, and the Core is light. As of release 11.0.0, SuperTokens dropped MySQL and MongoDB — PostgreSQL 13+ is the supported database, which Railway's managed Postgres satisfies. The Core itself is a single lightweight Java process; most resource use is in Postgres.

Typical cost: ~$5–10/month on Railway for the Core and Postgres. SuperTokens core features are open source and free; some enterprise features require a license key.

How It Compares

Auth0 and Cognito are managed but bill per active user. Authentik and Keycloak are standalone identity portals — great for SSO across many apps, heavier if you just want auth inside one app. SuperTokens hits the developer sweet spot: drop-in auth for your own app via SDK, self-hosted, no per-user fee.

Deploy in Under 5 Minutes

1. Click Deploy on Railway — SuperTokens Core and PostgreSQL build automatically (~3 minutes)
2. Confirm the connection URI uses the postgresql:// scheme and API_KEYS is set
3. Visit https://your-domain/hello — a Hello response confirms the database connection works
4. Install the backend SDK for your language (supertokens-node, supertokens-python, or Go)
5. Call supertokens.init() with your Railway domain as connectionURI and the API key as apiKey

Mount the SuperTokens middleware and your app gains auth endpoints with no route code to write.

Common Use Cases

• Add auth to your app — email/password, social, and passwordless login via SDK without building it yourself
• Replace Auth0 at scale — teams hitting per-MAU pricing move to self-hosted and pay only for infrastructure
• B2B multi-tenancy — give each customer organization an isolated auth context with the multi-tenancy recipe
• Data-residency compliance — keep user credentials inside your own Railway project for GDPR or regional laws
• Session management — secure, rotating session tokens handled by the Core instead of hand-rolled logic

Configuration

The connection URI must use postgresql://. SuperTokens rejects the postgres:// scheme Railway's default variables often produce, failing to start. This template forces the correct scheme — the most common SuperTokens deployment error, solved.

Keep API_KEYS private. It's the credential your backend uses to reach the Core. It's generated on deploy; use it as the apiKey in your SDK config and don't expose it client-side.

Dependencies for SuperTokens Hosting

• Railway account — ~$5–10/month for the Core and Postgres
• PostgreSQL 13+ (included; MySQL and MongoDB are no longer supported)
• A backend SDK for your app's language (Node.js, Python, or Go)
• Optional: a SuperTokens license key for enterprise features

Deployment Dependencies

• SuperTokens GitHub Repository
• Self-Hosting Documentation
• Docker Image Reference
• Railway Private Networking

Implementation Details

The template runs supertokens/supertokens-postgresql (a single Java 17 process) on port 3567 against a Railway-managed PostgreSQL service over the private network. The Core is stateless — all authentication data lives in Postgres — so no volume is required, and the database is the only thing to back up.

The connection is passed as POSTGRESQL_CONNECTION_URI using the postgresql:// scheme, which SuperTokens requires; the postgres:// form that Railway's default variables often generate causes a startup error, so the template ensures the correct scheme. API_KEYS is generated on deploy and authenticates backend SDK calls, and a /hello endpoint reports health. Integration happens in your app: the backend SDK is initialized with the Railway domain as connectionURI and the API key, after which SuperTokens middleware exposes the auth routes. Multiple "recipes" — email/password, passwordless, social login, session management, multi-tenancy — are enabled through SDK config rather than separate services.

Frequently Asked Questions

Why does the Core fail to start? Almost always the postgres:// versus postgresql:// scheme. SuperTokens requires postgresql://, but Railway's default Postgres variables often produce postgres://. This template forces the correct scheme, which is the most common cause of failed deploys.

Is SuperTokens a login portal or a backend service? A backend service. You run the Core and integrate an SDK into your app, which then exposes auth endpoints. For a standalone SSO portal across many apps, a full identity provider fits better; for auth inside your own app, SuperTokens is ideal.

How do I connect my app? Install the backend SDK for your language, call supertokens.init() with your Railway domain as connectionURI and the generated API key as apiKey, and mount the middleware. Your app then has sign-up, sign-in, and session endpoints.

Does it support social and passwordless login? Yes — email/password, social/OAuth providers, and passwordless (magic link, OTP) are all supported recipes, configured through the SDK.

Which databases are supported? PostgreSQL 13+ only. MySQL and MongoDB were dropped in release 11.0.0. Railway's managed Postgres meets the requirement.

Do I need a volume? No. The Core is stateless and all data lives in PostgreSQL, so there's nothing to persist on the Core itself. Back up the database.

Is it really free? Core features are open source and free. Some enterprise features require a license key added to the Core.

Why Deploy SuperTokens on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying SuperTokens on Railway you get a developer-friendly auth backend with the tricky part solved — the postgresql:// connection scheme handled, the API key generated, PostgreSQL wired over private networking, and automatic HTTPS. Add email, social, and passwordless authentication to your app at infrastructure-only cost, with your users' data on infrastructure you own.