Skip to main content
Version: 7.0

SuperTokens Authentication

To get started, run the setup command:

yarn rw setup auth supertokens

This installs all the packages, writes all the files, and makes all the code modifications you need.


You may have noticed that in api/src/functions/auth.ts there's an import from 'supertokens-node/framework/awsLambda'. This is fine, even if your app isn't running in a serverless environment like AWS Lambda. In "serverful" environments, Redwood automatically handles the translation between Fastify's request and reply objects and functions' AWS Lambda signature.

For a detailed explanation of all the api- and web-side changes that aren't exclusive to SuperTokens, see the top-level Authentication doc. For now, let's focus on SuperTokens's side of things.

When you run the setup command it configures your app to support both email+password logins as well as social auth logins (Apple, GitHub and Google). Working with those social auth logins does require quite a few environment variables. And SuperTokens itself needs a couple variables too. Thankfully SuperTokens makes this very easy to setup as they provide values we can use for testing.

Environment variables

The environment variables have to be added either to your project's .env file (when running in development environment), or to the environment variables of your hosting provider (when running in production).

Base setup

SUPERTOKENS_APP_NAME="Redwoodjs App" # this will be used in the email template for password reset or email verification emails.
SUPERTOKENS_CONNECTION_URI= # set to the correct connection uri

Production setup

Assuming that your web side is hosted on


Managed Supertokens service setup

SUPERTOKENS_API_KEY=your-api-key # The value can be omitted when self-hosting Supertokens

Social login setup

The following environment variables have to be set up (depending on the social login options):


redwood.toml setup

Make sure to modify redwood.toml to pass the required environment variables to the web side:

includeEnvironmentVariables = [

Page setup

Let's make sure: if this is a brand new project, generate a home page. There we'll try to sign up by destructuring signUp from the useAuth hook (import that from 'src/auth'). We'll also destructure and display isAuthenticated to see if it worked:

yarn rw g page home /
import { useAuth } from 'src/auth'

const HomePage = () => {
const { isAuthenticated, signUp } = useAuth()

return (
{/* MetaTags, h1, paragraphs, etc. */}

<p>{JSON.stringify({ isAuthenticated })}</p>
<button onClick={signUp}>sign up</button>

export default HomePage

Clicking sign up should navigate you to /auth where SuperToken's default login/sign up UI is rendered.

SuperTokens default UI

After you sign up, you should be redirected back to your Redwood app, and you should see {"isAuthenticated":true} on the page.


If going to http://localhost:8910/auth results in the plain Javascript file being served instead of the expected auth page, rename the web/src/auth.tsx file to web/src/authentication.tsx, and update the imports (related to