---
title: "Deploy SuperTokens — Open Source Auth for Your App"
description: "Self-host SuperTokens — email, social & passwordless auth SDK"
category: "Authentication"
url: https://railway.com/deploy/supertokens-auth-core
---

# Deploy SuperTokens — Open Source Auth for Your App

Self-host SuperTokens — email, social & passwordless auth SDK

**[Deploy SuperTokens — Open Source Auth for Your App on Railway](https://railway.com/template/supertokens-auth-core)**

- **Creator:** SilverBanana
- **Category:** Authentication

## Template content

### SuperTokens https://images.seeklogo.com/logo-png/48/1/supertokens-icon-logo-png_seeklogo-483542.png

- **Image:** supertokens/supertokens-postgresql

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# 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

| Service | Purpose |
| --- | --- |
| **SuperTokens Core** | The authentication engine and API on port `3567` (stateless Java service) |
| **PostgreSQL** | All authentication data — users, sessions, and recipe state |

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

| | SuperTokens (self-hosted) | Auth0 / Cognito | Authentik / Keycloak | Firebase Auth |
| --- | --- | --- | --- | --- |
| Cost model | Flat infra | Per active user | Flat infra | Per usage |
| Integration | Backend SDK | SDK / hosted | Standalone IdP | SDK |
| Login UI | Pre-built or custom | Hosted | Hosted portal | Pre-built |
| Data ownership | Full | Vendor | Full | Vendor |
| Best for | Devs adding auth to an app | Managed convenience | Standalone SSO/IdP | Google-stack apps |
| Self-hostable | Yes | No | Yes | No |

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

| Variable | Required | Description |
| --- | --- | --- |
| `POSTGRESQL_CONNECTION_URI` | Required | Postgres connection — **must** use the `postgresql://` scheme, not `postgres://` |
| `API_KEYS` | Required | Comma-separated API key(s) securing the Core — used as `apiKey` in your SDK |
| `POSTGRESQL_TABLE_NAMES_PREFIX` | Optional | Prefix for SuperTokens tables if sharing a database |
| `SUPERTOKENS_PORT` | Pre-set | `3567` — the Core's port |
| `SUPERTOKENS_HOST` | Pre-set | `0.0.0.0` so Railway can route to the Core |

> **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](https://github.com/supertokens/supertokens-core)
- [Self-Hosting Documentation](https://supertokens.com/docs/deployment/self-host-supertokens)
- [Docker Image Reference](https://github.com/supertokens/supertokens-docker-postgresql)
- [Railway Private Networking](https://docs.railway.com/guides/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.

## Similar templates

- [Keycloak](https://railway.com/deploy/mSwigX) — Keycloak template with keywind theme + apple and discord providers
- [lua-protector](https://railway.com/deploy/lua-protector) — Test deployed my project first
- [bknd](https://railway.com/deploy/p4nTYL) — Feature-rich yet lightweight backend

Open this page in a browser: https://railway.com/deploy/supertokens-auth-core