Skip to main content

Quickstart Guide

The following guide shows you how to use SuperTokens in an AWS Lambda environment. You can also check out the example repository for a full implementation.

Before you start

These instructions assume that you have completed the quickstart guide. If not, please go through it and create the example application before you start this tutorial.

Steps

caution

Follow the quickstart guide first to learn how to set up the frontend.

1. Set up API Gateway

1.1 Create a REST API Gateway

We will be using AWS API Gateway to create a REST API that will be used to communicate with our Lambda functions.

Create API gateway step UI

1.2 Set up authentication routes

Create a /auth resource and then /auth/{proxy+} resources. This will act as a catch-all for all SuperTokens auth routes. Enable CORS while creating the proxy resource.

Create proxy route step UI Route creation complete step UI

1.3 Attach lambda to the ANY method of the proxy resource

Click on the "ANY" method and then "Integration" to configure the lambda function. Check Lambda proxy integration and then select your lambda function.

Configure lambda integration UI
important

Ensure that the Lambda proxy integration toggle is turned on.

1.4 Enable CORS for the proxy path

Click on the {proxy+} resource and then "Enable CORS" button to open the CORS configuration page.

Enable CORS for the proxy path UI

In the CORS configuration page do the following:

  • Select the 'Default 4XX' and 'Default 5XX' checkboxes under Gateway responses
  • Select the 'OPTIONS' checkbox under Methods
  • Add rid,fdi-version,anti-csrf,st-auth-mode to the existing Access-Control-Allow-Headers
  • Set Access-Control-Allow-Origin to '<YOUR_WEBSITE_DOMAIN>'
  • Select Access-Control-Allow-Credentials checkbox
CORS configuration page

1.5 Deploy the API Gateway

Click the Deploy API button in the top right corner to deploy the API. During deployment, you'll be prompted to create a stage; for this tutorial, name the stage dev. After deployment, you will receive your Invoke URL.

important

Update apiDomain, apiBasePath, and apiGatewayPath in both Lambda configuration and your frontend config if they have changed post API Gateway configuration.

2. Set up Lambda layer

2.1 Create Lambda layer with required libraries

mkdir lambda && cd lambda

npm i -s supertokens-node @middy/core @middy/http-cors
mkdir nodejs && cp -r node_modules nodejs
zip -r supertokens-node.zip nodejs/

2.2 Upload SuperTokens lambda layer

Open AWS Lambda dashboard and click on layers:

AWS Lambda sidebar UI

Click "Create Layer" button:

Create layer button UI

Give a name for your layer, upload the zip and select the runtime

Lambda layer node configuration UI

3. Set up Lambda

3.1 Create a new lambda

Click "Create Function" in the AWS Lambda dashboard, enter the function name and runtime, and create your Lambda function.

Create new Lambda configurations UI Node

Scroll to the bottom and look for the Layers tab. Click on Add a layer

Link Lambda function with the Lambda layer

Select Custom Layer and then select the layer we created in the first step:

Link custom layer with Lambda function Node

3.3 Create a backend config file

Using the editor provided by AWS, create a new config file and write the following code:

App Info

Adjust these values based on the application that you are trying to configure. To learn more about what each field means check the references page.
This is the URL of your app's API server.
This is the URL of your app's API server.
SuperTokens will expose it's APIs scoped by this base API path.
This is the URL of your website.
The path where the login UI will be rendered
config.mjs
import EmailPassword from "supertokens-node/recipe/emailpassword";
import Session from "supertokens-node/recipe/session";

export 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/app-info
appName: "<YOUR_APP_NAME>",
apiDomain: "<YOUR_API_DOMAIN>",
websiteDomain: "<YOUR_WEBSITE_DOMAIN>",
apiBasePath: "/auth",
websiteBasePath: "/auth",
apiGatewayPath: "/dev"
},
recipeList: [
EmailPassword.init(),
Session.init(),
],
isInServerlessEnv: true,
}
}
important

In the above code, notice the extra config of apiGatewayPath that was added to the appInfo object. The value of this should be whatever you have set as the value of your AWS stage which scopes your API endpoints. For example, you may have a stage name per development environment:

  • One for development (/dev).
  • One for testing (/test).
  • One for prod (/prod).

So the value of apiGatewayPath should be set according to the above based on the environment it's running under.

You also need to change the apiBasePath on the frontend config to append the stage to the path. For example, if the frontend is query the development stage and the value of apiBasePath is /auth, you should change it to /dev/auth.

note

You may edit the apiBasePath and apiGatewayPath value later if you haven't setup the API Gateway yet.

3.4 Add the SuperTokens auth middleware

Using the editor provided by AWS, create/replace the handler file contents with the following code:

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

supertokens.init(getBackendConfig());

export const handler = middy(
middleware((event) => {
// SuperTokens middleware didn't handle the route, return your custom response
return {
body: JSON.stringify({
msg: "Hello!",
}),
statusCode: 200,
};
})
)
.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;
});
Add SuperTokens auth middleware UI
important

Since, we are using esm imports, we will need to set NODE_OPTIONS="--experimental-specifier-resolution=node" flag in the lambda environment variables. See the Node.js documentation for more information.

Configuring environment variables UI