Which frontend SDK do you use?

supertokens-web-js / mobile

supertokens-auth-react

Backend Integration

Supported frameworks

1) Install

NodeJS

npm i -s supertokens-node

GoLang

go get github.com/supertokens/supertokens-golang

Python

pip install supertokens-python

2) Initialise SuperTokens

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

NodeJS

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/signup/email/exists: To check if an email is already signed up
• GET /auth/signup/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/signup/email/exists: To check if an email is already signed up
• GET /auth/signup/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/signup/email/exists: To check if an email is already signed up
• GET /auth/signup/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 middlewaresapp.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/signup/email/exists: To check if an email is already signed up
• GET /auth/signup/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/signup/email/exists: To check if an email is already signed up
• GET /auth/signup/phonenumber/exists: To check if a phonenumber is already signed up

GoLang

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/signup/email/exists: To check if an email is already signed up
• GET /auth/signup/phonenumber/exists: To check if a phonenumber is already signed up

Python

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_headersfrom fastapi import FastAPIfrom starlette.middleware.cors import CORSMiddlewarefrom 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_headersfrom flask import Flask, abortfrom 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_headersfrom typing import Listfrom 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/signup/email/exists: To check if an email is already signed up
• GET /auth/signup/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

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 routesapp.use(errorHandler())
// your own error handlerapp.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.

GoLang

info

You can skip this step

Python

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)