Skip to main content

​
Quickstart

Get SuperTokens Core up and running on your local machine in just a few minutes.
1

Run with Docker

The fastest way to start SuperTokens Core is with Docker:
docker run -p 3567:3567 -d supertokens/supertokens-postgresql
This starts SuperTokens Core with an in-memory PostgreSQL database on port 3567.
For production, you should use an external database. See Database setup for details.
2

Verify it's running

Test that SuperTokens Core is responding by checking the health endpoint:
curl http://localhost:3567/hello
You should see:
{
  "status": "OK"
}
3

Create your first session

Let’s create a test session to verify the authentication flow works:
curl -X POST http://localhost:3567/recipe/session \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "test-user-123",
    "userDataInJWT": {},
    "userDataInDatabase": {},
    "enableAntiCsrf": false
  }'
You should receive a response with session tokens:
{
  "status": "OK",
  "session": {
    "handle": "...",
    "userId": "test-user-123",
    "userDataInJWT": {}
  },
  "accessToken": {
    "token": "...",
    "expiry": 1234567890,
    "createdTime": 1234567890
  },
  "refreshToken": {
    "token": "...",
    "expiry": 1234567890,
    "createdTime": 1234567890
  },
  "antiCsrfToken": null
}

​
What’s next?

Now that SuperTokens Core is running, you can:

Explore authentication methods

Learn about email/password, passwordless, social login, and more

Understand sessions

Deep dive into how session management works

Configure SuperTokens

Customize settings for your use case

Browse API reference

Explore all available endpoints

​
Running with different databases

​
PostgreSQL

docker run \
  -p 3567:3567 \
  -e POSTGRESQL_CONNECTION_URI="postgresql://username:password@host:5432/database" \
  -d supertokens/supertokens-postgresql

​
MySQL

docker run \
  -p 3567:3567 \
  -e MYSQL_CONNECTION_URI="mysql://username:password@host:3306/database" \
  -d supertokens/supertokens-mysql

​
MongoDB

docker run \
  -p 3567:3567 \
  -e MONGODB_CONNECTION_URI="mongodb://username:password@host:27017/database" \
  -d supertokens/supertokens-mongodb

​
Using with Backend SDKs

SuperTokens Core is designed to work with Backend SDKs. Here’s a quick example with Node.js:

​
Install the Backend SDK

npm install supertokens-node

​
Initialize the SDK

import supertokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
import EmailPassword from "supertokens-node/recipe/emailpassword";

supertokens.init({
  framework: "express",
  supertokens: {
    // This is the connection URI for SuperTokens Core
    connectionURI: "http://localhost:3567",
    apiKey: "optional-api-key"
  },
  appInfo: {
    appName: "My App",
    apiDomain: "http://localhost:3001",
    websiteDomain: "http://localhost:3000"
  },
  recipeList: [
    EmailPassword.init(),
    Session.init()
  ]
});
For complete integration examples with different Backend SDKs (Python, Go, etc.), see the SuperTokens documentation.

​
Production deployment

For production use, you’ll want to:
  1. Use an external database: Don’t rely on in-memory storage
  2. Configure API keys: Secure the connection between your Backend SDK and Core
  3. Set up proper networking: Keep Core on a private network
  4. Enable monitoring: Configure logging and health checks
See the Self-hosting guide for detailed production deployment instructions.

​
Troubleshooting

​
Port already in use

If port 3567 is already in use, you can change it: 
docker run -p 8080:3567 -d supertokens/supertokens-postgresql
Then connect to http://localhost:8080 instead.

​
Connection refused

Make sure:
  • Docker is running
  • The container started successfully: docker ps
  • Check logs: docker logs <container-id>

​
Database connection errors

If using an external database, verify:
  • The database server is accessible
  • Credentials are correct
  • The database exists and user has proper permissions
See Database setup troubleshooting for more help.

​
Learn more

Architecture

Understand how SuperTokens components work together

Docker deployment

Full Docker and docker-compose setup guide

Configuration reference

Complete list of all configuration options

Multi-tenancy

Set up multi-tenant applications

Build docs developers (and LLMs) love

Get started for freeTalk to us