Skip to main content

Backend Integration

Supported frameworks#

1) Install#

npm i -s supertokens-node

2) Initialise SuperTokens#

To learn more about what these properties mean read here.
Your app's name:*
Information about the question
This is the name of your application
API Domain:*
Information about the question
This is the URL of your app's API server.
API Base Path:
Information about the question
SuperTokens will expose it's APIs scoped by this base API path.
Website Domain:*
Information about the question
This is the URL of your website.
Website Base Path:
Information about the question
The path where the login UI will be rendered
Submit form

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

supertokens.init({
    framework: "express",
    supertokens: {
        connectionURI: "",
        apiKey: "",
    },
    appInfo: {
        // learn more about this on https://supertokens.com/docs/thirdpartyemailpassword/appinfo
        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";

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "...",
    },
    recipeList: [
        ThirdPartyEmailPassword.init({
            // 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.
            providers: [{
                config: {
                    thirdPartyId: "google",
                    clients: [{
                        clientId: "1060725074195-kmeum4crr01uirfl2op9kd5acmi9jutn.apps.googleusercontent.com",
                        clientSecret: "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"
                    }]
                }
            }, {
                config: {
                    thirdPartyId: "github",
                    clients: [{
                        clientId: "467101b197249757c71f",
                        clientSecret: "e97051221f4b6426e8fe8d51486396703012f5bd"
                    }]
                }
            }, {
                config: {
                    thirdPartyId: "apple",
                    clients: [{
                        clientId: "4398792-io.supertokens.example.service",
                        additionalConfig: {
                            keyId: "7M48Y4RYDL",
                            privateKey:
                                "-----BEGIN PRIVATE KEY-----\nMIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwIBAQQgu8gXs+XYkqXD6Ala9Sf/iJXzhbwcoG5dMh1OonpdJUmgCgYIKoZIzj0DAQehRANCAASfrvlFbFCYqn3I2zeknYXLwtH30JuOKestDbSfZYxZNMqhF/OzdZFTV0zc5u5s3eN+oCWbnvl0hM+9IW0UlkdA\n-----END PRIVATE KEY-----",
                            teamId: "YWQCXGJRJL",
                        }
                    }]
                }
            }],
        }),
        // ...
    ]
});

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

You can find the list of built in providers here. To add a provider that is not listed, you can follow our guide on setting up custom providers.

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

// 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:

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI