Which UI do you use?

Custom UI

Pre built UI

Backend Integration

Supported frameworks

1) Install

NodeJS

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

GoLang

npm i -s supertokens-node

Python

go get github.com/supertokens/supertokens-golang

Other Frameworks

pip install supertokens-python

2) Initialise SuperTokens

To learn more about what these properties mean read here.

Your app's name:*

This is the name of your application

API Domain:*

This is the URL of your app's API server.

API Base Path:

SuperTokens will expose it's APIs scoped by this base API path.

Website Domain:*

This is the URL of your website.

Website Base Path:

The path where the login UI will be rendered

Submit form

How do you want to identify your users?

Only phone numberOnly emailEmail or phone number

Which authentication type will you use?

OTPMagic linksOTP and Magic link

3) Add the SuperTokens APIs & CORS setup

To learn more about what these properties mean read here.

Your app's name:*

This is the name of your application

API Domain:*

This is the URL of your app's API server.

API Base Path:

SuperTokens will expose it's APIs scoped by this base API path.

Website Domain:*

This is the URL of your website.

Website Base Path:

The path where the login UI will be rendered

Submit form

NodeJS

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

GoLang

Express

info

Please refer the AWS lambda, Vercel or Netlify sections (In the Integrations section on the left nav bar)

Hapi

info

Please refer the NextJS section (In the Integrations section on the left nav bar)

Fastify

info

Please refer the NestJS section (In the Integrations section on the left nav bar)

Koa

important

• Add the middleware BEFORE all your routes.
• Add the cors middleware BEFORE the SuperTokens middleware as shown below.

import express from "express";
import cors from "cors";
import supertokens from "supertokens-node";
import {middleware} from "supertokens-node/framework/express";

let app = express();

app.use(cors({
    origin: "<YOUR_WEBSITE_DOMAIN>",
    allowedHeaders: ["content-type", ...supertokens.getAllCORSHeaders()],
    credentials: true,
}));

// IMPORTANT: CORS should be before the below line.
app.use(middleware());

// ...your API routes

This middleware adds a few APIs (see all the APIs here):

• POST /auth/signinup/code: For starting the passwordless login/sign up process
• POST /auth/signinup/code/resend: To generate and resend a code during an already started login/sign up process
• POST /auth/signinup/code/consume: For finishing the passwordless login/sign up process
• GET /auth/passwordless/email/exists: To check if an email is already signed up
• GET /auth/passwordless/phonenumber/exists: To check if a phonenumber is already signed up

Loopback

Register the plugin.

import Hapi from "@hapi/hapi";
import supertokens from "supertokens-node";
import { plugin } from "supertokens-node/framework/hapi";

const server = Hapi.server({ 
    port: 8000, 
    routes: {
        cors: {
            origin: ["<YOUR_WEBSITE_DOMAIN>"],
            additionalHeaders: [...supertokens.getAllCORSHeaders()],
            credentials: true,
        }
    }
});

(async() => {
    await server.register(plugin);

    await server.start();
})();

// ...your API routes

This plugin adds a few APIs (see all the APIs here) as well take care of all the errors thrown by the Supertokens library:

• POST /auth/signinup/code: For starting the passwordless login/sign up process
• POST /auth/signinup/code/resend: To generate and resend a code during an already started login/sign up process
• POST /auth/signinup/code/consume: For finishing the passwordless login/sign up process
• GET /auth/passwordless/email/exists: To check if an email is already signed up
• GET /auth/passwordless/phonenumber/exists: To check if a phonenumber is already signed up

Serverless

Register the plugin. Also register @fastify/formbody plugin.

import cors from "@fastify/cors";
import supertokens from "supertokens-node";
import { plugin } from "supertokens-node/framework/fastify";
import formDataPlugin from "@fastify/formbody";

import fastifyImport from "fastify";
let fastify = fastifyImport();

// ...other middlewares
(async () => {
    await fastify.register(cors, {
        origin: "<YOUR_WEBSITE_DOMAIN>",
        allowedHeaders: ['Content-Type', ...supertokens.getAllCORSHeaders()],
        credentials: true,
    })
    await fastify.register(formDataPlugin);
    await fastify.register(plugin);

    await fastify.listen(3000);
})();

// ...your API routes

This plugin adds a few APIs (see all the APIs here):

• POST /auth/signinup/code: For starting the passwordless login/sign up process
• POST /auth/signinup/code/resend: To generate and resend a code during an already started login/sign up process
• POST /auth/signinup/code/consume: For finishing the passwordless login/sign up process
• GET /auth/passwordless/email/exists: To check if an email is already signed up
• GET /auth/passwordless/phonenumber/exists: To check if a phonenumber is already signed up

Next.js

important

Add the middleware BEFORE all your routes.

import Koa from "koa";
import cors from '@koa/cors';
import supertokens from "supertokens-node";
import { middleware } from "supertokens-node/framework/koa";

let app = new Koa();

// ...other middlewares
app.use(cors({
    origin: "<YOUR_WEBSITE_DOMAIN>",
    allowHeaders: ["content-type", ...supertokens.getAllCORSHeaders()],
    credentials: true,
}));

app.use(middleware());

// ...your API routes

This middleware adds a few APIs (see all the APIs here):

• POST /auth/signinup/code: For starting the passwordless login/sign up process
• POST /auth/signinup/code/resend: To generate and resend a code during an already started login/sign up process
• POST /auth/signinup/code/consume: For finishing the passwordless login/sign up process
• GET /auth/passwordless/email/exists: To check if an email is already signed up
• GET /auth/passwordless/phonenumber/exists: To check if a phonenumber is already signed up

Nest.js

important

Add the middleware BEFORE all your routes.

import {RestApplication} from '@loopback/rest';
import supertokens from "supertokens-node";
import {middleware} from "supertokens-node/framework/loopback";

let app = new RestApplication({
    rest: {
        cors: {
            origin: "<YOUR_WEBSITE_DOMAIN>",
            allowedHeaders: ["content-type", ...supertokens.getAllCORSHeaders()],
            credentials: true
        }
    }
});

app.middleware(middleware);

// ...your API routes

This middleware adds a few APIs (see all the APIs here):

• POST /auth/signinup/code: For starting the passwordless login/sign up process
• POST /auth/signinup/code/resend: To generate and resend a code during an already started login/sign up process
• POST /auth/signinup/code/consume: For finishing the passwordless login/sign up process
• GET /auth/passwordless/email/exists: To check if an email is already signed up
• GET /auth/passwordless/phonenumber/exists: To check if a phonenumber is already signed up

Python

Chi

Use the supertokens.Middleware and the supertokens.GetAllCORSHeaders() functions as shown below.

import (
    "net/http"
    "strings"

    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    // SuperTokens init...

    http.ListenAndServe("SERVER ADDRESS", corsMiddleware(
        supertokens.Middleware(http.HandlerFunc(func(rw http.ResponseWriter,
        r *http.Request) {
            // TODO: Handle your APIs..

        }))))
}

func corsMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(response http.ResponseWriter, r *http.Request) {
        response.Header().Set("Access-Control-Allow-Origin", "<YOUR_WEBSITE_DOMAIN>")
        response.Header().Set("Access-Control-Allow-Credentials", "true")
        if r.Method == "OPTIONS" {
            // we add content-type + other headers used by SuperTokens
            response.Header().Set("Access-Control-Allow-Headers",
                strings.Join(append([]string{"Content-Type"},
                    supertokens.GetAllCORSHeaders()...), ","))
            response.Header().Set("Access-Control-Allow-Methods", "*")
            response.Write([]byte(""))
        } else {
            next.ServeHTTP(response, r)
        }
    })
}

net/http

Use the supertokens.Middleware and the supertokens.GetAllCORSHeaders() functions as shown below.

import (
    "net/http"

    "github.com/gin-contrib/cors"
    "github.com/gin-gonic/gin"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    // SuperTokens init...

    router := gin.New()

    // CORS
    router.Use(cors.New(cors.Config{
        AllowOrigins: []string{"<YOUR_WEBSITE_DOMAIN>"},
        AllowMethods: []string{"GET", "POST", "DELETE", "PUT", "OPTIONS"},
        AllowHeaders: append([]string{"content-type"},
            supertokens.GetAllCORSHeaders()...),
        AllowCredentials: true,
    }))

    // Adding the SuperTokens middleware
    router.Use(func(c *gin.Context) {
        supertokens.Middleware(http.HandlerFunc(
            func(rw http.ResponseWriter, r *http.Request) {
                c.Next()
            })).ServeHTTP(c.Writer, c.Request)
        // we call Abort so that the next handler in the chain is not called, unless we call Next explicitly
        c.Abort()
    })

    // Add APIs and start server
}

Gin

Use the supertokens.Middleware and the supertokens.GetAllCORSHeaders() functions as shown below.

import (
    "github.com/go-chi/chi"
    "github.com/go-chi/cors"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    // SuperTokens init...

    r := chi.NewRouter()

    // CORS
    r.Use(cors.Handler(cors.Options{
        AllowedOrigins: []string{"<YOUR_WEBSITE_DOMAIN>"},
        AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
        AllowedHeaders: append([]string{"Content-Type"},
            supertokens.GetAllCORSHeaders()...),
        AllowCredentials: true,
    }))

    // SuperTokens Middleware
    r.Use(supertokens.Middleware)

    // Add APIs and start server
}

Mux

Use the supertokens.Middleware and the supertokens.GetAllCORSHeaders() functions as shown below.

import (
    "net/http"

    "github.com/gorilla/handlers"
    "github.com/gorilla/mux"
    "github.com/supertokens/supertokens-golang/supertokens"
)

func main() {
    // SuperTokens init...

    // Add APIs

    router := mux.NewRouter()

    // Adding handlers.CORS(options)(supertokens.Middleware(router)))
    http.ListenAndServe("SERVER ADDRESS", handlers.CORS(
        handlers.AllowedHeaders(append([]string{"Content-Type"},
            supertokens.GetAllCORSHeaders()...)),
        handlers.AllowedMethods([]string{"GET", "POST", "PUT", "HEAD", "OPTIONS"}),
        handlers.AllowedOrigins([]string{"<YOUR_WEBSITE_DOMAIN>"}),
        handlers.AllowCredentials(),
    )(supertokens.Middleware(router)))
}

This Middleware adds a few APIs (see all the APIs here):

• POST /auth/signinup/code: For starting the passwordless login/sign up process
• POST /auth/signinup/code/resend: To generate and resend a code during an already started login/sign up process
• POST /auth/signinup/code/consume: For finishing the passwordless login/sign up process
• GET /auth/passwordless/email/exists: To check if an email is already signed up
• GET /auth/passwordless/phonenumber/exists: To check if a phonenumber is already signed up

Other Frameworks

FastAPI

Use the Middleware (BEFORE all your routes) and the get_all_cors_headers() functions as shown below.

from supertokens_python import get_all_cors_headers
from fastapi import FastAPI
from starlette.middleware.cors import CORSMiddleware
from supertokens_python.framework.fastapi import get_middleware

app = FastAPI()
app.add_middleware(get_middleware())

# TODO: Add APIs

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "<YOUR_WEBSITE_DOMAIN>"
    ],
    allow_credentials=True,
    allow_methods=["GET", "PUT", "POST", "DELETE", "OPTIONS", "PATCH"],
    allow_headers=["Content-Type"] + get_all_cors_headers(),
)

# TODO: start server

Flask

• Use the Middleware (BEFORE all your routes and after calling init function) and the get_all_cors_headers() functions as shown below.
• Add a route to catch all paths and return a 404. This is needed because if we don't add this, then OPTIONS request for the APIs exposed by the Middleware will return a 404.

from supertokens_python import get_all_cors_headers
from flask import Flask, abort
from flask_cors import CORS 
from supertokens_python.framework.flask import Middleware

app = Flask(__name__)
Middleware(app)

# TODO: Add APIs

CORS(
    app=app,
    origins=[
        "<YOUR_WEBSITE_DOMAIN>"
    ],
    supports_credentials=True,
    allow_headers=["Content-Type"] + get_all_cors_headers(),
)

# This is required since if this is not there, then OPTIONS requests for
# the APIs exposed by the supertokens' Middleware will return a 404
@app.route('/', defaults={'u_path': ''})  
@app.route('/<path:u_path>')  
def catch_all(u_path: str):
    abort(404)

# TODO: start server

Django

Use the Middleware and the get_all_cors_headers() functions as shown below in your settings.py.

from supertokens_python import get_all_cors_headers
from typing import List
from corsheaders.defaults import default_headers

CORS_ORIGIN_WHITELIST = [
    "<YOUR_WEBSITE_DOMAIN>"
]

CORS_ALLOW_CREDENTIALS = True

CORS_ALLOWED_ORIGINS = [
    "<YOUR_WEBSITE_DOMAIN>"
]

CORS_ALLOW_HEADERS: List[str] = list(default_headers) + [
    "Content-Type"
] + get_all_cors_headers()

INSTALLED_APPS = [
    'corsheaders',
    'supertokens_python'
]

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    ...,
    'supertokens_python.framework.django.django_middleware.middleware',
]

This Middleware adds a few APIs (see all the APIs here):

• POST /auth/signinup/code: For starting the passwordless login/sign up process
• POST /auth/signinup/code/resend: To generate and resend a code during an already started login/sign up process
• POST /auth/signinup/code/consume: For finishing the passwordless login/sign up process
• GET /auth/passwordless/email/exists: To check if an email is already signed up
• GET /auth/passwordless/phonenumber/exists: To check if a phonenumber is already signed up

4) Add the SuperTokens error handler

Add the errorHandler AFTER all your routes, but BEFORE your error handler

NodeJS

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

GoLang

Express

info

Please refer the AWS lambda, Vercel or Netlify sections (In the Integrations section on the left nav bar)

Hapi

info

Please refer the NextJS section (In the Integrations section on the left nav bar)

Fastify

info

Please refer the NestJS section (In the Integrations section on the left nav bar)

Koa

import express from "express";
import {errorHandler} from "supertokens-node/framework/express";

const app = express();
// ...your API routes

// Add this AFTER all your routes
app.use(errorHandler())

// your own error handler
app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
    // TODO
});

Loopback

No additional errorHandler is required.

Serverless

Add the errorHandler Before all your routes and plugin registration

import Fastify from "fastify";
import {errorHandler} from "supertokens-node/framework/fastify";

const fastify = Fastify();

fastify.setErrorHandler(errorHandler());

// ...your API routes

Next.js

No additional errorHandler is required.

Nest.js

No additional errorHandler is required.

Python

info

You can skip this step

Other Frameworks

info

You can skip this step

5) Setup the SuperTokens core

You need to now setup an instance of the SuperTokens core for your app (that your backend should connect to). You have two options:

• Managed service
• Self hosted with your own database (With Docker or Without Docker)