SuperTokens Getting Started: Self-Hosted Auth Setup (2026)

Getting started overview

SuperTokens is an open-source, self-hosted authentication solution designed for developers seeking full control over their user authentication and session management. Unlike managed authentication services, SuperTokens requires a multi-component setup, including a SuperTokens Core instance, a backend SDK integrated into your application server, and an optional frontend SDK for client-side interactions. This architecture ensures that user data and authentication logic reside within your infrastructure, aligning with specific data residency and customization requirements SuperTokens overview guide.

The initial setup involves deploying the SuperTokens Core, which manages the authentication logic and interacts with your chosen database. Following the core deployment, you integrate a SuperTokens backend SDK into your application's API layer. This SDK handles routes for user registration, login, session verification, and other authentication-related operations. Finally, if building a web application, a frontend SDK (e.g., for React, Vue, or Angular) can be integrated to provide pre-built UI components and manage client-side token handling SuperTokens guides overview.

This guide focuses on the fundamental steps to get a basic SuperTokens authentication flow operational, covering the deployment of the SuperTokens Core, the integration of a backend SDK, and initiating your first authenticated request.

Quick reference table

Create an account and get keys

SuperTokens does not operate as a traditional SaaS platform where you create an account to obtain API keys. Instead, it is a self-hosted solution. Your "credentials" and "keys" are primarily the configuration details you define during the setup of the SuperTokens Core and its integration with your application SuperTokens deployment guide.

SuperTokens Core deployment

The first step is to deploy the SuperTokens Core. This service acts as the central authentication server. You can deploy it using Docker, npm, or by compiling from source. For a quick start, Docker is often recommended:

docker pull supertokens/supertokens-core:latest
docker run -p 3567:3567 supertokens/supertokens-core:latest

This command pulls the latest SuperTokens Core Docker image and runs it, exposing its default port 3567. The Core will automatically initialize with an in-memory database for quick testing. For production, you would configure it to connect to a persistent database like PostgreSQL or MySQL SuperTokens database setup.

Backend SDK integration

Once the SuperTokens Core is running, integrate one of the SuperTokens backend SDKs into your application. These SDKs manage the communication with the SuperTokens Core and provide helper functions for authentication flows. For example, in a Node.js application, you would install the supertokens-node package:

npm install supertokens-node

Then, initialize the SDK in your application, providing the connection URI to your SuperTokens Core:

const supertokens = require("supertokens-node");
const Session = require("supertokens-node/recipe/session");
const EmailPassword = require("supertokens-node/recipe/emailpassword");

supertokens.init({
    framework: "express", // or "fastify", "hapi", "koa", etc.
    supertokens: {
        // These are the connection details of the SuperTokens core you deployed.
        connectionURI: "http://localhost:3567",
        apiKey: "", // Set if you have configured an API key for your Core
    },
    appInfo: {
        appName: "My SuperTokens App",
        apiDomain: "http://localhost:3001", // Your API domain
        websiteDomain: "http://localhost:3000", // Your website domain
        apiBasePath: "/auth",
    },
    recipeList: [
        EmailPassword.init(), // Enable EmailPassword authentication
        Session.init(), // Enable session management
    ],
});

The connectionURI is the crucial "credential" that links your backend to the SuperTokens Core. If you've configured an API key for your SuperTokens Core (recommended for production deployments), you would include it in the apiKey field SuperTokens Core API key configuration. The appInfo block defines metadata about your application, which is used for various internal SuperTokens operations, including cookie domains and CORS settings.

Your first request

To make your first authenticated request, you will typically perform a user registration, followed by a login, and then access a protected API route. This demonstrates the full lifecycle of a user session.

Backend setup for routes

Continuing with the Node.js example using Express, you would set up your Express app to use the SuperTokens middleware:

const express = require("express");
const supertokens = require("supertokens-node");
const { middleware } = require("supertokens-node/framework/express");
const { verifySession } = require("supertokens-node/recipe/session/framework/express");

const app = express();

// Add SuperTokens middleware to your Express app
app.use(middleware());

// Example protected API route
app.get("/api/protected", verifySession(), (req, res) => {
    res.json({ message: "This is protected data!", userId: req.session.getUserId() });
});

// Error handling middleware (must be after SuperTokens middleware)
app.use(supertokens.errorHandler());

app.listen(3001, () => {
    console.log("Backend server running on http://localhost:3001");
});

The middleware() function automatically handles SuperTokens-related routes like /auth/signup, /auth/signin, and /auth/signout based on the recipes you initialized. The verifySession() middleware protects the /api/protected route, ensuring only authenticated users can access it SuperTokens Express integration guide.

Performing registration and login

You can test these routes using a tool like Postman, Insomnia, or cURL. The apiBasePath defined in appInfo (/auth in our example) will be prefixed to all SuperTokens routes.

User registration

Send a POST request to http://localhost:3001/auth/signup with Content-Type: application/json and a body:

{
    "formFields": [
        { "id": "email", "value": "[email protected]" },
        { "id": "password", "value": "StrongPassword123!" }
    ]
}

A successful response will indicate the user has been created and will typically include session tokens in cookies.

User login

Send a POST request to http://localhost:3001/auth/signin with Content-Type: application/json and a body:

{
    "formFields": [
        { "id": "email", "value": "[email protected]" },
        { "id": "password", "value": "StrongPassword123!" }
    ]
}

Upon successful login, the server will set new session cookies (sAccessToken and sRefreshToken) in your client. These cookies are automatically managed by the SuperTokens backend SDK and, if used, the frontend SDK SuperTokens session management details.

Accessing a protected route

After logging in, make a GET request to http://localhost:3001/api/protected. Ensure your client sends the cookies received during login with this request. If the session is valid, you should receive the protected data:

{
    "message": "This is protected data!",
    "userId": "..."
}

If the session is invalid or missing, the verifySession() middleware will automatically return an unauthorized response (typically 401 or 403 status code).

Common next steps

After successfully completing your first authenticated request, consider these common next steps to further develop your SuperTokens integration:

• Frontend Integration: For web applications, integrate a SuperTokens frontend SDK (e.g., React, Vue, Angular) to manage client-side authentication flows, render pre-built UI components, and handle session token refreshing automatically SuperTokens frontend integration.
• Database Configuration: Switch the SuperTokens Core from its default in-memory database to a persistent database like PostgreSQL or MySQL for production environments. This ensures user data and sessions are stored durably SuperTokens database setup guide.
• Customization: Explore the extensive customization options for SuperTokens UI, authentication flows, and backend logic. SuperTokens allows modification of email templates, error messages, and even the core authentication logic through hooks and custom recipes SuperTokens customization options.
• Add More Recipes: Implement additional authentication recipes like social login (Google, GitHub), passwordless login (email, phone OTP), or multi-factor authentication (MFA) based on your application's requirements SuperTokens authentication recipes.
• Deployment Best Practices: Review deployment best practices for SuperTokens Core, including securing the Core with an API key, setting up HTTPS, and configuring CORS headers correctly for production environments SuperTokens production deployment.
• Understanding OAuth 2.0 and OpenID Connect: SuperTokens provides an authentication layer. For broader identity management and authorization flows, understanding standards like OAuth 2.0 authorization framework and OpenID Connect identity layer can provide context for how modern authentication systems operate, even if SuperTokens directly implements its own session management.

Troubleshooting the first call

Encountering issues during the initial setup is common. Here are some troubleshooting steps:

• SuperTokens Core Not Running: Ensure the SuperTokens Core service is actively running and accessible from your backend application. Check the Docker container status or the process if running directly. Verify that port 3567 (or your configured port) is open and not blocked by a firewall.
• Incorrect connectionURI: Double-check the connectionURI in your backend SDK initialization. It must accurately point to the SuperTokens Core instance (e.g., http://localhost:3567 or the appropriate IP/hostname).
• CORS Errors: If you are making requests from a different domain (e.g., a frontend running on localhost:3000 to a backend on localhost:3001), you might encounter Cross-Origin Resource Sharing (CORS) errors. Ensure your backend application is configured to allow CORS requests from your frontend's domain. SuperTokens handles some CORS aspects automatically via appInfo.websiteDomain and appInfo.apiDomain, but explicit configuration in your backend may still be necessary for other routes SuperTokens CORS configuration.
• Missing appInfo Configuration: Verify that appInfo.apiDomain and appInfo.websiteDomain are correctly set in your backend initialization. These are critical for cookie handling and session management across domains.
• Session Cookies Not Sent/Received: When testing with tools like Postman or cURL, ensure that cookies are being sent and received correctly. Many tools require explicit configuration to handle cookies across requests. If using a browser, ensure it's not blocking third-party cookies if your frontend and backend are on different subdomains.
• SuperTokens Error Handler: Make sure the SuperTokens error handling middleware (app.use(supertokens.errorHandler()) in Express) is correctly placed after all SuperTokens middleware and routes. This helps catch and format SuperTokens-specific errors SuperTokens error handling documentation.
• Check Core Logs: Review the logs of your SuperTokens Core instance for any errors or warnings. These logs often provide specific details about connection issues, database problems, or misconfigurations.
• SDK Version Compatibility: Ensure that your SuperTokens Core version and backend SDK version are compatible. While SuperTokens aims for backward compatibility, major version jumps might introduce breaking changes SuperTokens versioning policy.