Initial Setup - SuperTokens Docs

Initial Setup

Enable email verification to ensure user authenticity and protect application routes.

Add required or optional email verification.

Add SuperTokens email verification to this application. Inspect the existing recipes and determine whether verification should be REQUIRED or OPTIONAL; ask if the business rule is unclear. Configure the backend and frontend EmailVerification and Session recipes consistently, add the required UI routes or custom flow, and verify protected-route behavior. Account for passwordless email behavior and keep delivery credentials in environment variables. Run the relevant tests, typechecks, and build.

Overview

Email verification needs to be explicitly configured to work in your SuperTokens integration. The functionality offers two ways to set it up:

Before you start

For passwordless login, with email, a user’s email is automatically marked as verified when they login. Therefore, this flow only triggers if a user changes their email during a session.

Steps

1. Initialize the backend recipe

Language: Node.js

import SuperTokens from "supertokens-node";
import EmailVerification from "supertokens-node/recipe/emailverification";
import Session from "supertokens-node/recipe/session";

SuperTokens.init({
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    EmailVerification.init({
      mode: "REQUIRED", // or "OPTIONAL"
    }),
    Session.init(),
  ],
});

2. Initialize the frontend recipe

UI type

Language: React

import SuperTokens, { SuperTokensWrapper } from "supertokens-auth-react";
import { getSuperTokensRoutesForReactRouterDom } from "supertokens-auth-react/ui";
import EmailVerification from "supertokens-auth-react/recipe/emailverification";
import { EmailVerificationPreBuiltUI } from "supertokens-auth-react/recipe/emailverification/prebuiltui";
import Session from "supertokens-auth-react/recipe/session";
import reactRouterDOM, { Routes, BrowserRouter as Router, Route } from "react-router-dom";

SuperTokens.init({
  appInfo: {
    apiDomain: "...",
    appName: "...",
    websiteDomain: "...",
  },
  recipeList: [
    EmailVerification.init({
      mode: "REQUIRED", // or "OPTIONAL"
    }),
    Session.init(),
  ],
});

function App() {
  return (
    <SuperTokensWrapper>
      <div className="App">
        <Router>
          <div className="fill">
            <Routes>
              {getSuperTokensRoutesForReactRouterDom(reactRouterDOM, [
                /* Other pre-built UI */ EmailVerificationPreBuiltUI,
              ])}
              // ... other routes
            </Routes>
          </div>
        </Router>
      </div>
    </SuperTokensWrapper>
  );
}

3. Send the email verification email

After a user signs up, or when the email verification validators fail, you need to tell the user about the email verification process. Redirect them to a screen that informs them about the current status and call the verification API.

import { sendVerificationEmail } from "supertokens-web-js/recipe/emailverification";

async function sendEmail() {
  try {
    let response = await sendVerificationEmail();
    if (response.status === "EMAIL_ALREADY_VERIFIED_ERROR") {
      window.location.assign("/home");
    } else {
      window.alert("Please check your email and click the link in it");
    }
  } catch (err) {
    window.alert("Oops! Something went wrong.");
  }
}

4. Verify the email after the user clicks the link

Once the user clicks the email verification link, call the following function. It extracts the token and tenantId from the link and calls the token verification API.

import { verifyEmail } from "supertokens-web-js/recipe/emailverification";

async function consumeVerificationCode() {
  try {
    let response = await verifyEmail();
    if (response.status === "EMAIL_VERIFICATION_INVALID_TOKEN_ERROR") {
      window.alert("Oops! Seems like the verification link expired. Please try again");
      window.location.assign("/auth/verify-email");
    } else {
      window.location.assign("/home");
    }
  } catch (err) {
    window.alert("Oops! Something went wrong.");
  }
}

References

Verification email

This is how the email that the user receives looks like:

You can find the source code of this template on GitHub.

Verification link lifetime

By default, the email verification link’s lifetime is 1 day.