Quickstart

Get SuperTokens Core running in 5 minutes

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

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