Skip to main content

Backend Integration

Supported frameworks#

1) Install#

npm i -s supertokens-node

2) Initialise SuperTokens#

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

import supertokens from "supertokens-node";
import Session from "supertokens-node/recipe/session";
import ThirdPartyEmailPassword from"supertokens-node/recipe/thirdpartyemailpassword";

framework: "express",
supertokens: {
connectionURI: "",
apiKey: "",
appInfo: {
// learn more about this on
appName: "<YOUR_APP_NAME>",
apiDomain: "<YOUR_API_DOMAIN>",
websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
apiBasePath: "/auth",
websiteBasePath: "/auth"
recipeList: [
ThirdPartyEmailPassword.init({/*TODO: See next step*/}),
Session.init() // initializes session features

3) Initialise Social login providers#

Populate the providers array with the third party auth providers you want.

import SuperTokens from "supertokens-node";
import ThirdPartyEmailPassword from "supertokens-node/recipe/thirdpartyemailpassword";
let { Google, Github, Apple } = ThirdPartyEmailPassword;

appInfo: {
apiDomain: "...",
appName: "...",
websiteDomain: "...",
recipeList: [
providers: [
// We have provided you with development keys which you can use for testing.
// IMPORTANT: Please replace them with your own OAuth keys for production use.
clientId: "",
clientSecret: "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"
clientId: "467101b197249757c71f",
clientSecret: "e97051221f4b6426e8fe8d51486396703012f5bd"
clientId: "4398792-io.supertokens.example.service",
clientSecret: {
keyId: "7M48Y4RYDL",
"-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgu8gXs+XYkqXD6Ala9Sf/iJXzhbwcoG5dMh1OonpdJUmgCgYIKoZIzj0DAQehRANCAASfrvlFbFCYqn3I2zeknYXLwtH30JuOKestDbSfZYxZNMqhF/OzdZFTV0zc5u5s3eN+oCWbnvl0hM+9IW0UlkdA\n-----END PRIVATE KEY-----",
// Facebook({
// clientSecret: "FACEBOOK_CLIENT_SECRET",
// })
// ...

When you want to generate your own keys, please refer to the corresponding documentation to get your client ids and client secrets for each of the below providers:

  • Generate your client ID and secret by following the docs here
  • Set the authorisation callback URL to <YOUR_WEBSITE_DOMAIN>/auth/callback/google
  • Generate your client ID and secret by following the docs here
  • Set the authorisation callback URL to <YOUR_WEBSITE_DOMAIN>/auth/callback/github
  • Generate your client ID and secret by following the docs here
  • Set the authorisation callback URL to <YOUR_WEBSITE_DOMAIN>/auth/callback/facebook

Make sure to enable https to be able to use the test users of the Facebook app. On http://localhost, the login flow can be verified only with the app's admin user.

  • Generate your client ID and secret by following this article
  • Set the authorisation callback URL to <YOUR_API_DOMAIN>/auth/callback/apple. Note that Apple doesn't allow localhost in the URL. So if you are in dev mode, you can use the dev keys we have provided above.

4) Add the SuperTokens APIs & CORS setup#

  • 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();

allowedHeaders: ["content-type", ...supertokens.getAllCORSHeaders()],
credentials: true,

// IMPORTANT: CORS should be before the below line.

// ...your API routes

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

  • POST /auth/signinup: For signing up/signing in a user using a thirdparty provider.
  • POST /auth/signup: For signing up a user with email & password
  • POST /auth/signin: For signing in a user with email & password

5) Add the SuperTokens error handler#

import { errorHandler } from "supertokens-node/framework/express";
import express from "express";
let app = express();
// ...your API routes

// Add this AFTER all your routes

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

6) 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: