Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

Backend Integration

Supported frameworks#

Node.js logoPython logoGolang logo

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 EmailPassword from"supertokens-node/recipe/emailpassword";
import ThirdParty from"supertokens-node/recipe/thirdparty";

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: [
        EmailPassword.init(),
        ThirdParty.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 ThirdParty from "supertokens-node/recipe/thirdparty"
import EmailPassword from "supertokens-node/recipe/emailpassword"

SuperTokens.init({
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "...",
    },
    recipeList: [
        EmailPassword.init(),
        ThirdParty.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.
            signInAndUpFeature: {
                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