Netlify

Learn to set up SuperTokens authentication with Netlify using serverless functions.

Overview

The following guide gets you though how to add SuperTokens to a Netlify serverless API. You can also check out the example repository for a full working example.

Before you start

This guide assumes that you are using Netlify for hosting your serverless API functions. If this is not the case, and you are only hosting your frontend using Netlify, please follow the Quick setup guide instead.

Steps

1. Setup the frontend

Follow the initial quickstart guide to configure the frontend.

2. Setup the backend

2.1 Install the SuperTokens node package

npm i supertokens-node

yarn add supertokens-node

pnpm add supertokens-node

bun add supertokens-node

2.2 Create a configuration file

Create a config folder in the root directory of your project. Create a supertokensConfig.js inside the config folder. An example of this file can be found here.

2.3 Create a backend configuration function

import EmailPassword from "supertokens-node/recipe/emailpassword";
import Session from "supertokens-node/recipe/session";

function getBackendConfig() {
  return {
    framework: "awsLambda",
    supertokens: {
      connectionURI: "<CORE_API_ENDPOINT>",
      apiKey: "<YOUR_API_KEY>",
    },
    appInfo: {
      // learn more about this on https://supertokens.com/docs/references/backend-sdks/reference#sdk-configuration
      appName: "<YOUR_APP_NAME>",
      apiDomain: "<YOUR_API_DOMAIN>",
      websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
      apiBasePath: "/auth",
      websiteBasePath: "/auth",
    },
    recipeList: [EmailPassword.init(), Session.init()],
    isInServerlessEnv: true,
  };
}

module.exports.getBackendConfig = getBackendConfig;

3. Expose the authentication APIs

We will add all the backend APIs for auth on /.netlify/functions/auth/*. This can be changed by setting the apiBasePath property in the appInfo object on the backend and frontend. For the rest of this page, we will assume you are using /.netlify/functions/auth/*.

3.1 Create the netlify/functions/auth.js page

Be sure to create the netlify/functions/ folder. An example of this can be found here.

import supertokens from "supertokens-node";
import { middleware } from "supertokens-node/framework/awsLambda";
import middy from "@middy/core";
import cors from "@middy/http-cors";
import { getBackendConfig } from "../../config/supertokensConfig";

supertokens.init(getBackendConfig());

module.exports.handler = middy(
  middleware(async (event, context) => {
    if (event.httpMethod === "OPTIONS") {
      return {
        statusCode: 200,
        body: "",
      };
    }

    return {
      statusCode: 404,
      body: "Not Found",
    };
  }),
)
  .use(
    cors({
      origin: getBackendConfig().appInfo.websiteDomain,
      credentials: true,
      headers: ["Content-Type", ...supertokens.getAllCORSHeaders()].join(", "),
      methods: "OPTIONS,POST,GET,PUT,DELETE",
    }),
  )
  .onError((request) => {
    throw request.error;
  });

3.2 Use the login widget

If you are now able to sign in or sign up, this means the backend setup is done correctly! If not, please feel free to ask questions on Discord

4. Add session verification

For this guide, we will assume that we want an API /.netlify/functions/user GET which returns the current session information.

4.1 Create a new file netlify/functions/user.js

An example of this is here.

4.2 Call the supertokens.init function

Remember that whenever we want to use any functions from the supertokens-node lib, we have to call the supertokens.init function at the top of that serverless function file.

import supertokens from "supertokens-node";
import { getBackendConfig } from "../../config/supertokensConfig";

supertokens.init(getBackendConfig());

4.3 Use session verification with your API handler

We use the verifySession() middleware to verify a session.

import supertokens from "supertokens-node";
import { verifySession } from "supertokens-node/recipe/session/framework/awsLambda";
import { SessionEvent } from "supertokens-node/framework/awsLambda";
import middy from "@middy/core";
import cors from "@middy/http-cors";
import { getBackendConfig } from "../../config/supertokensConfig";

supertokens.init(getBackendConfig());

const handler = async (event: SessionEvent) => {
  return {
    body: JSON.stringify({
      sessionHandle: event.session!.getHandle(),
      userId: event.session!.getUserId(),
      accessTokenPayload: event.session!.getAccessTokenPayload(),
    }),
  };
};

module.exports.handler = middy(verifySession(handler))
  .use(
    cors({
      origin: getBackendConfig().appInfo.websiteDomain,
      credentials: true,
      headers: ["Content-Type", ...supertokens.getAllCORSHeaders()].join(", "),
      methods: "OPTIONS,POST,GET,PUT,DELETE",
    }),
  )
  .onError((request) => {
    throw request.error;
  });