useMfaEnrollment

useMfaEnrollment() reads the signed-in user’s two-factor (authenticator-app) status and exposes the four management actions: start enrollment, confirm the first code, disable the factor, and regenerate recovery codes. Build a custom security screen with it, or use the prebuilt <MfaEnrollment> (which already wraps this and is embedded in <UserProfile>’s Security section).

Enrolling requires the project’s Pro plan or higher. The mutating actions resolve a MutationResult; a wrong code surfaces as a failure with error.status === 401.

When to use it

• Build a bespoke “two-factor authentication” settings panel.
• Render your own QR code from the otpauth:// URI, or show only the manual setup key.

Usage

import { useMfaEnrollment } from '@torii-js/torii-react';

function TwoFactor() {
  const { mfa, enroll, confirm } = useMfaEnrollment();

  async function start() {
    const result = await enroll();
    if (!result.ok) return alert(result.error.message);
    // result.value.otpauthUri  → render as a QR code
    // result.value.secret      → show for manual entry
    const code = prompt('Enter the 6-digit code from your app');
    if (code) {
      const confirmed = await confirm(code);
      if (confirmed.ok) alert(`Recovery codes: ${confirmed.value.recoveryCodes.join(', ')}`);
    }
  }

  return mfa?.enabled ? <span>Two-factor is on</span> : <button onClick={start}>Enable</button>;
}

Returns

Name	Type	Description
mfa	MfaStatus | null	{ enabled, recoveryCodesRemaining }, or null while loading / signed out.
isLoading	boolean	true while the status is being fetched.
error	ToriiError | null	Error from the last fetch or action, or null.
refresh	() => Promise<void>	Re-fetch the status from the server.
enroll	() => Promise<MutationResult<MfaEnrollment>>	Start enrollment. value is { otpauthUri, secret }.
confirm	(code: string) => Promise<MutationResult<{ recoveryCodes: string[] }>>	Confirm the first code and activate the factor; returns single-use recovery codes (shown once).
disable	(code: string) => Promise<MutationResult<void>>	Remove the factor; requires a current code.
regenerate	(code: string) => Promise<MutationResult<{ recoveryCodes: string[] }>>	Replace the recovery codes; requires a current code.
enrolling / confirming / disabling / regenerating	boolean	Per-action in-flight flags.

Notes

• The shared secret and recovery codes are returned once, at enrollment / regeneration. Torii stores the secret encrypted and the recovery codes hashed; neither can be read back, so surface them to the user immediately.
• A wrong code on confirm / disable / regenerate resolves { ok: false } with error.status === 401: keep the form open for a retry rather than treating it as a hard failure.

TypeScript

import type { UseMfaEnrollmentReturn, MfaStatus } from '@torii-js/torii-react';