Skip to content
SuperTokens Docs
Esc
↑↓navigate↵open⌘Jpreview
Dashboard
On this page

Multi-Factor Authentication

Add email or SMS OTP, TOTP, or WebAuthn passkeys as MFA factors and require step-up authentication for sensitive actions.

Overview

Multi-factor authentication (MFA) is a security process that requires users to verify their identity through multiple forms of credentials before gaining access to a system. SuperTokens allows you to integrate MFA in your application using Email/SMS One-Time Password (OTP), Time-based One-Time Password (TOTP), or WebAuthn/Passkeys.

Prerequisites

Enable paid features

This feature is only available to paid users. Follow the instructions below to enable it.

Managed Service

  1. Sign in to the SuperTokens dashboard.
  2. Select the managed service option from the service type select component.
  3. Select your core instance from the next elemenet or create a new one.
  4. Open Features sub-page and enable the required ones.

Self Hosted

  1. Sign in to the SuperTokens dashboard.
  2. Select the self-hosted option from the service type select component.
  3. Select your license key from the next elemenet or create a new one. Then enable the required features.
  4. If the key is not yet configured, add it to your Core service. If your Core already uses this key, no configuration changes are required.

Magic link via email or SMS is only supported as a first factor for pre-built UI. It will not work as a second factor because if the magic link is opened on a different device, there would be no reference to the existing session (which was created before first factor completion). Instead, you can use OTP based authentication, using email or SMS. It achieves the same level of security as a magic link.

Getting started

The quickest way to get a glimpse of how MFA works with SuperTokens is to use the example app. Run the following command to get started:

npx create-supertokens-app@latest --recipe=multifactorauth

Besides that, you can check the initial quickstart guide for step-by-step instructions, along with the other guides for more specific use cases.

Before you explore a guide, read through the Important Concepts page first. It explains multiple topics that get used in each tutorial.

Important Concepts

Go through a quick explanation of how MFA works and some common terminologies.

Quickstart Guide

Implement an authentication flow that uses MFA.

Implement Step Up Authentication

Require additional authentication challenges on specific routes or actions.

Implement Recovery Codes

Allow users to recover their account if they lose access to one of the factors.

Customization

To adjust the functionality to fit your use case you can explore different sections from the documentation.

Require TOTP for all users

Force all users to use TOTP.

Require TOTP for specific users

Enable TOTP only for some of the users.

Require OTP for all users

Force all users to use OTP.

Require OTP for specific users

Enable OTP only for some of the users.

WebAuthn

Use WebAuthn as a secondary factor

Protect frontend and backend routes

Check for the MFA status on specific routes.

API reference

API schema and response details