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

Add the code below to your server's init file.

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 supertokens from "supertokens-node";import Session from "supertokens-node/recipe/session";import EmailPassword from "supertokens-node/recipe/emailpassword";
supertokens.init({    framework: "express",    supertokens: {        connectionURI: "",        apiKey: "",    },    appInfo: {        // learn more about this on https://supertokens.com/docs/session/appinfo        appName: "<YOUR_APP_NAME>",        apiDomain: "<YOUR_API_DOMAIN>",        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",        apiBasePath: "/auth",        websiteBasePath: "/auth",    },    recipeList: [        EmailPassword.init(), // initializes signin / sign up features        Session.init() // initializes session features    ]});

Loopback

import supertokens from "supertokens-node";import Session from "supertokens-node/recipe/session";import EmailPassword from "supertokens-node/recipe/emailpassword";
supertokens.init({    framework: "hapi",    supertokens: {        connectionURI: "",        apiKey: "",    },    appInfo: {        // learn more about this on https://supertokens.com/docs/session/appinfo        appName: "<YOUR_APP_NAME>",        apiDomain: "<YOUR_API_DOMAIN>",        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",        apiBasePath: "/auth",        websiteBasePath: "/auth",    },    recipeList: [        EmailPassword.init(), // initializes signin / sign up features        Session.init() // initializes session features    ]});

Serverless

import supertokens from "supertokens-node";import Session from "supertokens-node/recipe/session";import EmailPassword from "supertokens-node/recipe/emailpassword";
supertokens.init({    framework: "fastify",    supertokens: {        connectionURI: "",        apiKey: "",    },    appInfo: {        // learn more about this on https://supertokens.com/docs/session/appinfo        appName: "<YOUR_APP_NAME>",        apiDomain: "<YOUR_API_DOMAIN>",        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",        apiBasePath: "/auth",        websiteBasePath: "/auth",    },    recipeList: [        EmailPassword.init(), // initializes signin / sign up features        Session.init() // initializes session features    ]});

Next.js

import supertokens from "supertokens-node";import Session from "supertokens-node/recipe/session";import EmailPassword from "supertokens-node/recipe/emailpassword";
supertokens.init({    framework: "koa",    supertokens: {        connectionURI: "",        apiKey: "",    },    appInfo: {        // learn more about this on https://supertokens.com/docs/session/appinfo        appName: "<YOUR_APP_NAME>",        apiDomain: "<YOUR_API_DOMAIN>",        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",        apiBasePath: "/auth",        websiteBasePath: "/auth",    },    recipeList: [        EmailPassword.init(), // initializes signin / sign up features        Session.init() // initializes session features    ]});

Nest.js

import supertokens from "supertokens-node";import Session from "supertokens-node/recipe/session";import EmailPassword from "supertokens-node/recipe/emailpassword";
supertokens.init({    framework: "loopback",    supertokens: {        connectionURI: "",        apiKey: "",    },    appInfo: {        // learn more about this on https://supertokens.com/docs/session/appinfo        appName: "<YOUR_APP_NAME>",        apiDomain: "<YOUR_API_DOMAIN>",        websiteDomain: "<YOUR_WEBSITE_DOMAIN>",        apiBasePath: "/auth",        websiteBasePath: "/auth",    },    recipeList: [        EmailPassword.init(), // initializes signin / sign up features        Session.init() // initializes session features    ]});

GoLang

import (    "github.com/supertokens/supertokens-golang/recipe/emailpassword"    "github.com/supertokens/supertokens-golang/recipe/session"    "github.com/supertokens/supertokens-golang/supertokens")
func main() {    apiBasePath := "/auth"    websiteBasePath := "/auth"    err := supertokens.Init(supertokens.TypeInput{        Supertokens: &supertokens.ConnectionInfo{            ConnectionURI: "",            APIKey: "",        },        AppInfo: supertokens.AppInfo{            AppName: "<YOUR_APP_NAME>",            APIDomain: "<YOUR_API_DOMAIN>",            WebsiteDomain: "<YOUR_WEBSITE_DOMAIN>",            APIBasePath: &apiBasePath,            WebsiteBasePath: &websiteBasePath,        },        RecipeList: []supertokens.Recipe{            emailpassword.Init(nil),            session.Init(nil),        },    })
    if err != nil {        panic(err.Error())    }}

Python

FastAPI

from supertokens_python import init, InputAppInfo, SupertokensConfigfrom supertokens_python.recipe import emailpassword, session
init(    app_info=InputAppInfo(        app_name="<YOUR_APP_NAME>",        api_domain="<YOUR_API_DOMAIN>",        website_domain="<YOUR_WEBSITE_DOMAIN>",        api_base_path="/auth",        website_base_path="/auth"    ),    supertokens_config=SupertokensConfig(        connection_uri="",        api_key=""    ),    framework='fastapi',    recipe_list=[        session.init(), # initializes session features        emailpassword.init()    ],    mode='asgi' # use wsgi if you are running using gunicorn)

Flask

from supertokens_python import init, InputAppInfo, SupertokensConfigfrom supertokens_python.recipe import emailpassword, session
init(    app_info=InputAppInfo(        app_name="<YOUR_APP_NAME>",        api_domain="<YOUR_API_DOMAIN>",        website_domain="<YOUR_WEBSITE_DOMAIN>",        api_base_path="/auth",        website_base_path="/auth"    ),    supertokens_config=SupertokensConfig(        connection_uri="",        api_key=""    ),    framework='flask',    recipe_list=[        session.init(), # initializes session features        emailpassword.init()    ])

Django

from supertokens_python import init, InputAppInfo, SupertokensConfigfrom supertokens_python.recipe import emailpassword, session
init(    app_info=InputAppInfo(        app_name="<YOUR_APP_NAME>",        api_domain="<YOUR_API_DOMAIN>",        website_domain="<YOUR_WEBSITE_DOMAIN>",        api_base_path="/auth",        website_base_path="/auth"    ),    supertokens_config=SupertokensConfig(        connection_uri="",        api_key=""    ),    framework='django',    recipe_list=[        session.init(), # initializes session features        emailpassword.init()    ],    mode='asgi' # use wsgi if you are running django server in sync mode)

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/signup: For signing up a user with email & password
• POST /auth/signin: For signing in a user with email & password

Loopback

Register the plugin.

import Hapi from "@hapi/hapi";import supertokens from "supertokens-node";import { plugin } from "supertokens-node/framework/hapi";
let 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/signup: For signing up a user with email & password
• POST /auth/signin: For signing in a user with email & password

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 middlewaresfastify.register(cors, {    origin: "<YOUR_WEBSITE_DOMAIN>",    allowedHeaders: ['Content-Type', ...supertokens.getAllCORSHeaders()],    credentials: true,});
(async () => {    await fastify.register(formDataPlugin);    await fastify.register(plugin);
    await fastify.listen(8000);})();
// ...your API routes

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

• POST /auth/signup: For signing up a user with email & password
• POST /auth/signin: For signing in a user with email & password

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();
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/signup: For signing up a user with email & password
• POST /auth/signin: For signing in a user with email & password

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/signup: For signing up a user with email & password
• POST /auth/signin: For signing in a user with email & password

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...
    // TODO: 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/signup: For signing up a user with email & password
• POST /auth/signin: For signing in a user with email & password

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',]# TODO: start server

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

• POST /auth/signup: For signing up a user with email & password
• POST /auth/signin: For signing in a user with email & password

4) Add the SuperTokens 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, { Request, Response, NextFunction } from 'express';import { errorHandler } from "supertokens-node/framework/express";
let app = express();
// ...your API routes
// Add this AFTER all your routesapp.use(errorHandler())
// your own error handlerapp.use((err: unknown, req: Request, res: Response, next: NextFunction) => { /* ... */ });

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";
let 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)