---
title: Netlify
description: Learn to set up SuperTokens authentication with Netlify using serverless functions.
sidebar:
  icon: /docs-assets/img/logos/netlify.svg
  order: 60
---

## Overview

The following guide gets you though how to add SuperTokens to a Netlify serverless API.
You can also check out the [example repository](https://github.com/supertokens/supertokens-auth-react/tree/master/examples/with-netlify) 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](/quickstart#1-integrate-the-frontend-sdk) instead.

## Steps

### 1. Setup the frontend

Follow the [initial quickstart guide](/quickstart#1-integrate-the-frontend-sdk) to configure the frontend.

### 2. Setup the backend

#### 2.1 Install the SuperTokens node package

<CodeGroup group="package-managers">
```bash title="npm"
npm i supertokens-node
```

```bash title="Yarn"
yarn add supertokens-node
```

```bash title="pnpm"
pnpm add supertokens-node
```

```bash title="Bun"
bun add supertokens-node
```
</CodeGroup>

#### 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](https://github.com/supertokens/supertokens-auth-react/blob/master/examples/with-netlify/config/supertokensConfig.js).

#### 2.3 Create a backend configuration function


```tsx title="/config/supertokensConfig.ts"
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](https://github.com/supertokens/supertokens-auth-react/blob/master/examples/with-netlify/netlify/functions/auth.js).

```tsx title="netlify/functions/auth.ts" check=false reason="Requires surrounding framework application context"
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;
  });
```

:::note[- Notice that we called `supertokens.init` above. We will need to call this in all API endpoints that use any functions related to SuperTokens.]
- `CORS` is only needed if you are hosting your frontend using a separate domain (if your website domain is different that your API's domain).
:::

#### 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](https://supertokens.com/discord)

### 4. Add session verification

:::warning[This guide only applies to scenarios which involve **SuperTokens Session Access Tokens**.]

If you are implementing either, [**Unified Login**](/authentication/unified-login/introduction) or [**Microservice Authentication**](/authentication/m2m/introduction), features that make use of **OAuth2 Access Tokens**, please check the [separate page](/authentication/unified-login/verify-tokens) that shows you how to verify those types of tokens.
:::

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](https://github.com/supertokens/supertokens-auth-react/blob/master/examples/with-netlify/netlify/functions/user.js).

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

```tsx title="netlify/functions/user.ts" check=false reason="Requires surrounding framework application context"
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.

```tsx title="netlify/functions/user.ts" check=false reason="Requires surrounding framework application context"
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;
  });
```