---
title: "Deploy SuperTokens"
description: "Self-hosted SuperTokens 12.2 auth core with Postgres, private API key."
category: "Authentication"
url: https://railway.com/deploy/supertokens-1
---

# Deploy SuperTokens

Self-hosted SuperTokens 12.2 auth core with Postgres, private API key.

**[Deploy SuperTokens on Railway](https://railway.com/template/supertokens-1)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/supertokens-1/manifest.json

- **Creator:** Agaz Self-Host
- **Category:** Authentication

## Template content

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

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

### supertokens https://avatars.githubusercontent.com/u/50478857?s=512&v=4

- **Image:** supertokens/supertokens-postgresql:12.2.0
- **Start command:** `docker-entrypoint.sh supertokens start --host=::`
- **Health check:** /hello

## Documentation

# Deploy and Host SuperTokens on Railway

SuperTokens is an open-source authentication platform and a self-hosted alternative to Auth0, Firebase Auth and Cognito. It provides email/password, passwordless, social login, passkeys, multi-factor authentication and session management. Your backend talks to the SuperTokens core through official SDKs for Node.js, Python and Go, while frontend SDKs handle login screens.

## About Hosting SuperTokens

This template deploys the SuperTokens core, pinned to v12.2.0, alongside a Railway Postgres database that stores users, sessions and signing keys. The core has no public domain. It listens on Railway's private network, and every request must carry the API key generated at deploy time. Database tables are created automatically on first start. Nothing is stored on disk, and memory use is modest, so the Hobby plan is enough. Your backend service (on Railway) connects using the `SUPERTOKENS_CONNECTION_URI` and `API_KEYS` variables. Login screens and the user management dashboard are served by the SuperTokens SDK inside your own backend and frontend.

## Common Use Cases

- Adding email/password, social login, passwordless or passkey sign-in to a web or mobile app without paying per monthly active user
- Session management with rotating refresh tokens and anti-CSRF for Node.js, Python or Go APIs
- Keeping user identities in your own Postgres database for compliance or data residency

## Dependencies for SuperTokens Hosting

- `supertokens/supertokens-postgresql:12.2.0` (official image, core v12.2.0)
- Railway Postgres (`ghcr.io/railwayapp-templates/postgres-ssl:18`) with a volume
- A backend using a SuperTokens SDK (Node.js, Python or Go) to call the core

### Deployment Dependencies

- [SuperTokens self-hosting docs](https://supertokens.com/docs/deployment/self-host-supertokens)
- [SuperTokens core v12.2.0 release notes](https://github.com/supertokens/supertokens-core/releases/tag/v12.2.0)
- [SuperTokens backend SDKs](https://supertokens.com/docs/quickstart/backend-setup)
- [Railway private networking](https://docs.railway.com/reference/private-networking)

### Implementation Details

| Service | Image | Networking | Storage |
| --- | --- | --- | --- |
| supertokens | `supertokens/supertokens-postgresql:12.2.0` | private only, port 3567 | none (all state in Postgres) |
| Postgres | Railway Postgres 18 | private only | volume |

Connect from your backend service on Railway with references:

```env
SUPERTOKENS_CONNECTION_URI=${{supertokens.SUPERTOKENS_CONNECTION_URI}}
SUPERTOKENS_API_KEY=${{supertokens.API_KEYS}}
```

Node.js example:

```js
supertokens.init({
  supertokens: {
    connectionURI: process.env.SUPERTOKENS_CONNECTION_URI,
    apiKey: process.env.SUPERTOKENS_API_KEY,
  },
  appInfo: { appName: "My App", apiDomain: "https://api.example.com", websiteDomain: "https://example.com" },
  recipeList: [EmailPassword.init(), Session.init(), Dashboard.init()],
});
```

| Variable | Default | Purpose |
| --- | --- | --- |
| `API_KEYS` | generated 48-character secret | Required on every request to the core |
| `POSTGRESQL_CONNECTION_URI` | `${{Postgres.DATABASE_URL}}` | Database connection |
| `SUPERTOKENS_CONNECTION_URI` | `http://:3567` | Convenience value for your backend to reference |

Notes:

- The core listens on `::` (via the start command `docker-entrypoint.sh supertokens start --host=::`) so it is reachable over Railway's IPv6 private network.
- If your backend runs outside Railway, add a public domain on port 3567. The API key still protects the core, but keep it secret and rotate it by editing `API_KEYS` (comma-separate old and new keys during a rotation).
- The user management dashboard is enabled through the `Dashboard` recipe in your backend SDK and is served at `/auth/dashboard`.
- Back up the Postgres database; it holds all users and sessions.

This is a community-maintained deployment package and does not imply affiliation with or endorsement by SuperTokens.

## 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 are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.


## 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-1