Backend Integration

Supported frameworks#

1) Install#

NodeJS
GoLang
Python

npm i -s supertokens-node

go get github.com/supertokens/supertokens-golang

pip install supertokens-python

2) Initialise SuperTokens#

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

NodeJS
GoLang
Python

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
    ]
});

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
    ]
});

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
    ]
});

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
    ]
});

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
    ]
});

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())
    }
}

FastAPI
Flask
Django

from supertokens_python import init, InputAppInfo, SupertokensConfig
from 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
)

from supertokens_python import init, InputAppInfo, SupertokensConfig
from 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()
    ]
)

from supertokens_python import init, InputAppInfo, SupertokensConfig
from 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
GoLang
Python

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

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

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
fastify.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

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

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

Chi
net/http
Gin
Mux

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)
        }
    })
}

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
}

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
}

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

FastAPI
Flask
Django

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

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

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',
]
# 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
GoLang
Python

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 routes
app.use(errorHandler())

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

No additional errorHandler is required.

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

No additional errorHandler is required.

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)