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:
REQUIRED: The user needs to verify before they can access any protected routes.OPTIONAL: The sessions include information about the email verification status, but it is up to you to enforce the requirement based on your business logic.
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
- Pre-built UI
- Drop-in components that handle the flows for you.
- Custom UI
- Build your own UI and call the SDK directly.
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.