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 ThirdParty from "supertokens-node/recipe/thirdparty";
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: [        ThirdParty.init({/*TODO: See next step*/}),        Session.init() // initializes session features    ]});
NOTE

Notice that SuperTokens.init uses both the ThirdParty and Session recipes. ThirdParty provides the login feature and Session is used for session management (post login).

3) Initialise Social login providers#

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

import SuperTokens from "supertokens-node";import ThirdParty from "supertokens-node/recipe/thirdparty";
const { Google, Github, Apple } = ThirdParty;
SuperTokens.init({    appInfo: {        apiDomain: "...",        appName: "...",        websiteDomain: "...",    },    recipeList: [        ThirdParty.init({            signInAndUpFeature: {                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.                    Google({                        clientId: "1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps.googleusercontent.com",                        clientSecret: "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"                    }),                    Github({                        clientId: "467101b197249757c71f",                        clientSecret: "e97051221f4b6426e8fe8d51486396703012f5bd"                    }),                    Apple({                        clientId: "4398792-io.supertokens.example.service",                        clientSecret: {                            keyId: "7M48Y4RYDL",                            privateKey:                                "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgu8gXs+XYkqXD6Ala9Sf/iJXzhbwcoG5dMh1OonpdJUmgCgYIKoZIzj0DAQehRANCAASfrvlFbFCYqn3I2zeknYXLwtH30JuOKestDbSfZYxZNMqhF/OzdZFTV0zc5u5s3eN+oCWbnvl0hM+9IW0UlkdA\n-----END PRIVATE KEY-----",                            teamId: "YWQCXGJRJL",                        },                    }),                    // Facebook({                    //     clientSecret: "FACEBOOK_CLIENT_SECRET",                    //     clientId: "FACEBOOK_CLIENT_ID"                    // })                ]            }        }),        // ...    ]});

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:

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

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.

Apple
  • 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#

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: For signing up/signing in a user using a thirdparty provider.

5) Add the SuperTokens error handler#

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

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) => { /* ... */ });

6) Test if sign up is setup correctly#

  • Visit the login form on the website.
  • Try to sign up.
  • If after signing up, you are redirected to /, everything is setup correctly 😁
  • If not, you can always ask for help via Github issues or via our Discord. You should even checkout the Troubleshooting section on the left navigation section.

7) Setup the SuperTokens core#

Are you using https://try.supertokens.com as the connection URI in the init function?
YesNo
What type of UI do you want to use?
Custom UI
Pre built UI