Netlify Guide
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
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
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.
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/app-info
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;
});
- 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
4. Add session verification
This guide only applies to scenarios which involve SuperTokens Session Access Tokens.
If you are implementing either, Unified Login or Microservice Authentication, features that make use of OAuth2 Access Tokens, please check the separate page 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.
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;
});