Skip to main content

​
Dashboard Setup

  1. Go to the Security page.
  2. In the Account MFA section, enable your desired methods (TOTP and/or Passkeys).
  3. (Optional) Toggle “Require at onboarding” to force MFA setup during signup.
  4. (Optional) Toggle “Session-based MFA” to require MFA for every new session.

​
Your UI SDK Implementation

  • Trigger gating: Check userWithMissingInfo?.scope for requiresAdditionalAuth.
  • Detect MFA: Use useSyncMfaFlow to know when to prompt.
  • Add device: Call addDevice() → show QR from uri (install qrcode).
  • Verify: authenticateDevice({ code }) → fetch and show recovery codes → completeAcknowledgement().
  • Refresh: Call getUserDevices() after verification.
import { useMfa, useSyncMfaFlow, useDynamicContext } from "@dynamic-labs/sdk-react-core";

export function AccountTotpMfa() {
  const {
    addDevice,
    authenticateDevice,
    getUserDevices,
    getRecoveryCodes,
    completeAcknowledgement,
  } = useMfa();
  const { userWithMissingInfo } = useDynamicContext();

  useSyncMfaFlow({
    handler: async () => {
      if (userWithMissingInfo?.scope?.includes("requiresAdditionalAuth")) {
        const devices = await getUserDevices();
        if (devices.length === 0) {
          const { uri } = await addDevice();
          // Render QR from `uri`, then prompt for OTP
          return;
        }
        // Prompt for OTP
      } else {
        // MFA already satisfied; show recovery codes if needed
        const codes = await getRecoveryCodes();
        // Show `codes` to the user, then:
        await completeAcknowledgement();
      }
    },
  });

  const verifyOtp = async (code: string) => {
    await authenticateDevice({ code });
    const codes = await getRecoveryCodes();
    // Show `codes` to the user, then:
    await completeAcknowledgement();
    // Refresh device list
    await getUserDevices();
  };

  return null;
}
Only one verified TOTP device per user
  • Recovery codes are single-use. Regenerate with getRecoveryCodes(true) if needed.
Troubleshooting
  • Error: “401 Unauthorized” when adding a second TOTP device — only one device is supported; delete the existing device first.
  • QR code not displaying — ensure qrcode is installed: npm install qrcode @types/qrcode.
  • Recovery codes not working — each code is single-use; generate new codes if exhausted.

​
Dynamic UI Implementation

With the Dynamic UI, account-based MFA prompts appear automatically during onboarding/login when additional authentication is required. To explicitly trigger in your app, use useSyncMfaFlow to detect the requirement and usePromptMfaAuth to open the UI. Note: The Dynamic UI is method-agnostic. It automatically prompts with whichever MFA method(s) you have enabled (TOTP and/or Passkeys), so separate TOTP/Passkey tabs are not required here. 
import { useSyncMfaFlow, useDynamicContext, usePromptMfaAuth } from "@dynamic-labs/sdk-react-core";

const { userWithMissingInfo } = useDynamicContext();
const promptMfaAuth = usePromptMfaAuth();

useSyncMfaFlow({
  handler: async () => {
    if (userWithMissingInfo?.scope?.includes("requiresAdditionalAuth")) {
      // Opens the Dynamic UI to complete account-based MFA
      await promptMfaAuth(); // No MFA token needed for account-based MFA
    }
  },
});

​
Programmatic MFA Modal Controls

Dynamic SDKs provide granular control over individual MFA modal screens. These methods allow you to programmatically show and hide specific MFA screens in your application.

​
Available Modal Controls

For React applications, use the useDynamicModals hook to control MFA modal visibility: 
import { useDynamicModals } from '@dynamic-labs/sdk-react-core';

export function MfaModalControls() {
  const {
    setShowMFAManage,
    setShowMfaChooseType,
    setShowMfaQRCode,
    setShowOTPVerification,
    setShowMfaViewBackupCodes,
    setShowMfaEnterBackupCodes,
  } = useDynamicModals();

  return (
    <div>
      <button onClick={() => setShowMFAManage(true)}>
        Show MFA Management
      </button>
      <button onClick={() => setShowMfaChooseType(true)}>
        Show MFA Type Selection
      </button>
      <button onClick={() => setShowMfaQRCode(true)}>
        Show QR Code
      </button>
      <button onClick={() => setShowOTPVerification(true)}>
        Show OTP Verification
      </button>
      <button onClick={() => setShowMfaViewBackupCodes(true)}>
        Show Backup Codes
      </button>
      <button onClick={() => setShowMfaEnterBackupCodes(true)}>
        Show Enter Backup Codes
      </button>
    </div>
  );
}