User MFA Management

The UserMFAManagement component lets users enroll, view, and delete their own multi-factor authentication factors in a single card-based interface using the My Account API. It uses the My Account API’s authentication methods management capabilities to render a complete UI for managing a user’s authentication methods. With the UserMFAManagement component, you do not need to orchestrate navigation, call API endpoints, or manage state.

User MFA Management component showing available and enrolled verification methods

Supported factors

The component handles every authentication method factor configured with the My Account API.

Factor	What the component renders
Email OTP	Email input → 6-digit OTP verification
SMS OTP	Country-code picker + phone entry → 6-digit OTP verification
TOTP (Authenticator application)	QR code with manual-entry key → 6-digit OTP verification
Push notifications	QR code for Auth0 Guardian scan → “waiting for approval” state
Passkeys	Educational screen → OS biometric prompt → enrolled entry in the list
Recovery codes	Display-once code list with a copy action and an “I’ve saved my codes” confirmation

Configure your application

Select your framework to configure environment variables and universal components.

React (SPA)
Next.js (RWA)
shadcn

Setup requirements

Before rendering the UserMFAManagement component, follow Build Account Security UI to configure your Auth0 tenant and applications.

Enable MFA methods and scopes

Enable MFA methods

Navigate to Dashboard > Security > Multi-factor Auth.
Enable the desired factors. To learn more, read Multi-Factor Authentication Factors.

Configure My Account API permissionsConfigure the My Account API User-delegated Access permissions in Build Account Security UI. All five permissions are required for the complete authentication-method management flow.

Install the component

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

npm install @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form and @tanstack/react-query are peer dependencies. The command also installs the @auth0/universal-components-core dependency for shared utilities and Auth0 integration.

Get started

import { UserMFAManagement } from "@auth0/universal-components-react";

export function SecurityPage() {
  return <UserMFAManagement />;
}

Components are always imported from the root entry @auth0/universal-components-react, regardless of framework.
Only the Auth0ComponentProvider component uses a framework-specific subpath: /spa for React applications, /rwa for Next.js applications.

Full integration example

import React from "react";
import { UserMFAManagement } from "@auth0/universal-components-react";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onBefore: (factor) => window.confirm(`Remove your ${factor} authenticator?`),
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: {
            title: "Two-Factor Authentication",
            description: "Manage the extra verification methods used to protect your account.",
          },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Setup requirements

Before rendering the UserMFAManagement component, follow Build Account Security UI to configure your Auth0 tenant and applications.

Enable MFA methods and scopes

Enable MFA methods

Navigate to Dashboard > Security > Multi-factor Auth.
Enable the desired factors. To learn more, read Multi-Factor Authentication Factors.

Install the component

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

npm install @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form and @tanstack/react-query are peer dependencies. The command also installs the @auth0/universal-components-core dependency for shared utilities and Auth0 integration.

Get started

app/security/page.tsx

"use client";

import { UserMFAManagement } from "@auth0/universal-components-react";

export default function SecurityPage() {
  return <UserMFAManagement />;
}

Full integration example

app/security/page.tsx

"use client";

import { UserMFAManagement } from "@auth0/universal-components-react";
import { analytics } from "@/lib/analytics";

export default function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: { title: "Two-Factor Authentication" },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

Setup requirements

Before rendering the UserMFAManagement component, follow Build Account Security UI to configure your Auth0 tenant and applications.

Enable MFA methods and scopes

Enable MFA methods

Navigate to Dashboard > Security > Multi-factor Auth.
Enable the desired factors. To learn more, read Multi-Factor Authentication Factors.

Install the component

npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-mfa-management.json

The install command adds the component source into src/components/auth0/my-account/ along with all UI dependencies and the @auth0/universal-components-core dependency for shared utilities and Auth0 integration.

Get started

import { UserMFAManagement } from "@/components/auth0/my-account/user-mfa-management";

export function SecurityPage() {
  return <UserMFAManagement />;
}

Full integration example

import React from "react";
import { UserMFAManagement } from "@/components/auth0/my-account/user-mfa-management";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserMFAManagement
        factorConfig={{
          phone: { visible: true, enabled: true },
          totp: { visible: true, enabled: true },
          "push-notification": { visible: true, enabled: true },
          email: { visible: true, enabled: true },
          "recovery-code": { visible: true, enabled: true },
          "webauthn-platform": { visible: false },
          "webauthn-roaming": { visible: false },
        }}
        enrollAction={{
          onAfter: (factor) => {
            analytics.track("MFA Factor Enrolled", { factor });
          },
        }}
        deleteAction={{
          onBefore: (factor) => window.confirm(`Remove your ${factor} authenticator?`),
          onAfter: (factor) => {
            analytics.track("MFA Factor Deleted", { factor });
          },
        }}
        customMessages={{
          header: { title: "Two-Factor Authentication" },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Props

Display props

Display props control how the component renders without affecting its behavior.

Prop	Type	Default	Description
`hideHeader`	`boolean`	`false`	Hide the component header (title and description).
`readOnly`	`boolean`	`false`	Disable all mutation actions (enroll and delete). Factors are shown but cannot be added or removed.
`showActiveOnly`	`boolean`	`false`	Show only factor types that the user has at least one active enrollment for. Factor types with no enrollments are hidden.
`disableEnroll`	`boolean`	`false`	Hide the enroll button for all factor types. Users can still delete existing factors.
`disableDelete`	`boolean`	`false`	Hide the delete button on all enrolled factor rows. Users can still enroll new factors.
`factorConfig`	`Partial <Record<MFAType, { visible?: boolean; enabled?: boolean }>>`	`{}`	Per-factor-type visibility and enabled state.

factorConfig Use factorConfig to show or grey-out specific factor types without editing the tenant configuration. Each key is a factor type string; both fields are optional and default to true. Supported factor type keys: phone, totp, email, push-notification, webauthn-platform, webauthn-roaming, recovery-code.

visible renders the factor row in the list (false to hide).
enabled renders the factor row is interactive (false renders it greyed-out and non-interactive).

<UserMFAManagement
  factorConfig={{
    phone: { visible: true, enabled: true },
    totp: { visible: true, enabled: true },
    email: { visible: true, enabled: false }, // shown but greyed-out
    "webauthn-platform": { visible: false },  // hidden entirely
  }}
/>

Action props

Action props let you hook into the component’s enrollment and deletion lifecycle events and trigger or cancel operations.

Prop	Type	Description
`enrollAction`	`ComponentAction<MFAType>`	Lifecycle hooks for factor enrollment. Set `disabled: true` to disable the enrollment action.
`deleteAction`	`ComponentAction<MFAType>`	Lifecycle hooks for factor deletion. Set `disabled: true` to disable the deletion action.

enrollAction Use onBefore to cancel enrollment before the flow starts. Use onAfter to refresh related UI or send analytics after enrollment completes successfully.

<UserMFAManagement
  enrollAction={{
    onBefore: (factor) => window.confirm(`Enroll ${factor}?`),
    onAfter: (factor) => {
      analytics.track("MFA Factor Enrolled", { factor });
    },
  }}
/>

deleteAction Use onBefore to cancel deletion before the built-in confirmation dialog is shown. onAfter runs after a factor is successfully deleted.

<UserMFAManagement
  deleteAction={{
    onBefore: (factor) =>
      window.confirm(`Remove your ${factor} authenticator? You may be locked out if this is your only factor.`),
    onAfter: (factor) => {
      analytics.track("MFA Factor Deleted", { factor });
    },
  }}
/>

Customize props

Customization props let you adapt copy, validation rules, and styling without modifying source code.

Prop	Type	Description
`customMessages`	`Partial<UserMfaManagementMessages>`	Override default UI text and translations.
`styling`	`ComponentStyling<UserMFAManagementClasses>`	CSS variables and class overrides.
`schema`	`{ email?: RegExp; phone?: RegExp }`	Custom validation patterns for email and phone number input fields.

customMessages Customize all text and translations. Every field is optional.

Available Messages

Header header.title, header.description, no_active_mfa, loading_text, component_error.title, component_error.descriptionActions actions.remove_button_label, actions.cancel_button_label, actions.confirm_button_label, actions.continue_button_label, actions.submit_button_label, actions.verify_button_label, actions.back_button_label, actions.deleting_button_text, actions.menu_aria_labelPer factor type (replace {factor} with phone, totp, email, push-notification, webauthn-platform, webauthn-roaming, or recovery-code) factors.{factor}.title, factors.{factor}.description, factors.{factor}.button_textNotifications notifications.factor_enroll_success, notifications.factor_remove_success, notifications.fetch_factors_error, notifications.factor_delete_errorEnrollment and removal enrollment and remove_factor_dialog

<UserMFAManagement
  customMessages={{
    header: {
      title: "Two-Factor Authentication",
      description: "Add extra layers of security to protect your account.",
    },
    no_active_mfa: "You haven't enrolled any authentication methods yet.",
    factors: {
      phone: {
        title: "Text message (SMS)",
        description: "Receive a one-time code via text message.",
        button_text: "Add method",
      },
      totp: {
        title: "Authenticator app",
        description: "Use Google Authenticator, Authy, or any TOTP app.",
      },
    },
    notifications: {
      fetch_factors_error: "Unable to load your security methods.",
    },
  }}
/>

Customize style Customize appearance with CSS variables and class overrides. Supports light/dark themes.

Available Styling Options

Variables—CSS custom properties

common Applied to both themes
light Light mode only
dark Dark mode only

Class overrides

UserMFAManagement-item each factor-type card container
EnrollFactorModal-dialogContent the enrollment multi-step dialog content area
FactorDeleteModal-dialogContent the delete confirmation dialog content area

<UserMFAManagement
  styling={{
    variables: {
      light: { "--color-primary": "#4f46e5" },
      dark: { "--color-primary": "#818cf8" },
    },
    classes: {
      "UserMFAManagement-item": "rounded-2xl shadow-md border-2",
      "EnrollFactorModal-dialogContent": "max-w-lg",
      "FactorDeleteModal-dialogContent": "max-w-sm",
    },
  }}
/>

schema Override the built-in regex patterns used to validate user input during enrollment. Both fields are optional; unset fields keep their default patterns.

email validates the email address entered during email-OTP enrollment (default: standard RFC-5322-style pattern).
phone validates the phone number entered during SMS enrollment (default: accepts international E.164 format).

<UserMFAManagement
  schema={{
    // Restrict to company domain only
    email: /^[a-zA-Z0-9._%+-]+@example\.com$/,
    // US numbers only
    phone: /^\+1[2-9]\d{2}[2-9]\d{6}$/,
  }}
/>

TypeScript definitions

type MFAType =
  | "phone"
  | "totp"
  | "email"
  | "push-notification"
  | "webauthn-platform"
  | "webauthn-roaming"
  | "recovery-code";

interface FactorConfigOptions {
  visible?: boolean;
  enabled?: boolean;
}

interface UserMFAManagementClasses {
  "UserMFAManagement-item"?: string;
  "EnrollFactorModal-dialogContent"?: string;
  "FactorDeleteModal-dialogContent"?: string;
}

interface ComponentAction<Item, Context = void> {
  disabled?: boolean;
  onBefore?: (item: Item, context?: Context) => boolean;
  onAfter?: (item: Item, context?: Context) => void | boolean | Promise<boolean>;
}

interface UserMFAManagementProps {
  hideHeader?: boolean;
  showActiveOnly?: boolean;
  disableEnroll?: boolean;
  disableDelete?: boolean;
  readOnly?: boolean;
  factorConfig?: Partial<Record<MFAType, FactorConfigOptions>>;
  customMessages?: Partial<UserMfaManagementMessages>;
  styling?: ComponentStyling<UserMFAManagementClasses>;
  schema?: { email?: RegExp; phone?: RegExp };
  enrollAction?: ComponentAction<MFAType>;
  deleteAction?: ComponentAction<MFAType>;
}

Advanced customization

In addition to the component configuration described above, use the useUserMFA hook when you need to build a custom MFA management interface.

import { useUserMFA } from "@auth0/universal-components-react";

export function CustomMfaManagement() {
  const {
    factorsByType,
    isLoadingFactors,
    error,
    visibleFactorTypes,
    handleEnroll,
    handleDeleteFactor,
  } = useUserMFA({
    factorConfig: {
      phone: { visible: true, enabled: true },
      totp: { visible: true, enabled: true },
    },
  });

  if (isLoadingFactors) return <p>Loading authentication methods…</p>;
  if (error) return <p role="alert">{error}</p>;

  return (
    <ul>
      {visibleFactorTypes.map((factorType) => (
        <li key={factorType}>
          <button onClick={() => handleEnroll(factorType)}>
            Add {factorType}
          </button>
          {factorsByType[factorType]?.map((factor) => (
            <button
              key={factor.id}
              onClick={() => handleDeleteFactor(factor.id, factorType)}
            >
              Remove {factorType}
            </button>
          ))}
        </li>
      ))}
    </ul>
  );
}

The hook accepts showActiveOnly, readOnly, disableDelete, factorConfig, customMessages, enrollAction, and deleteAction. It returns factor data, loading and action state, enrollment and deletion state, and the handlers required to implement enrollment, verification, and removal flows. Use UserMFAManagement when you want the built-in interface. If you use the hook, implement the matching enrollment, verification, recovery-code, and deletion UI for the factor types you support.

onAfter in enrollAction and deleteAction runs when the success notification closes, rather than immediately when the action completes.

Web Components

iOS Components

Android Components

Supported factors

Configure your application

Setup requirements

Enable MFA methods and scopes

Install the component

Get started

Setup requirements

Enable MFA methods and scopes

Install the component

Get started

Setup requirements

Enable MFA methods and scopes

Install the component

Get started

Props

Display props

Action props

Customize props

TypeScript definitions

Advanced customization

Learn more

User Passkey Management

Build a Self-Service Account Security Interface

​Supported factors

​Configure your application

​Setup requirements

​Enable MFA methods and scopes

​Install the component

​Get started

​Setup requirements

​Enable MFA methods and scopes

​Install the component

​Get started

​Setup requirements

​Enable MFA methods and scopes

​Install the component

​Get started

​Props

​Display props

​Action props

​Customize props

​TypeScript definitions

​Advanced customization

​Learn more

User Passkey Management

Build a Self-Service Account Security Interface

Supported factors

Configure your application

Setup requirements

Enable MFA methods and scopes

Install the component

Get started

Setup requirements

Enable MFA methods and scopes

Install the component

Get started

Setup requirements

Enable MFA methods and scopes

Install the component

Get started

Props

Display props

Action props

Customize props

TypeScript definitions

Advanced customization

Learn more