Check MFA Authentication Status

isUserMissingMfaAuth

Checks if the user requires additional MFA authentication.

This function determines if the current user session requires additional multi-factor authentication to access certain features. This is typically used with session-based MFA to verify if a user needs to complete an MFA challenge.

The function checks for the presence of the requiresAdditionalAuth scope in the user’s JWT token.

Usage

import { isUserMissingMfaAuth } from '@dynamic-labs-sdk/client';

const checkMfaStatus = () => {
  const needsMfaAuth = isUserMissingMfaAuth();

  if (needsMfaAuth) {
    console.log('User needs to complete MFA authentication');
  } else {
    console.log('User has completed MFA authentication');
  }
};

Parameters

Parameter	Type	Description
client	DynamicClient (optional)	The Dynamic client instance. Only required when using multiple clients.

Returns

boolean - Returns true if the user needs additional MFA authentication, false otherwise.

Examples

Check and prompt for MFA

import {
  isUserMissingMfaAuth,
  getMfaMethods
} from '@dynamic-labs-sdk/client';

const handlePostLogin = async () => {
  const needsMfaAuth = isUserMissingMfaAuth();

  if (!needsMfaAuth) {
    // User doesn't need MFA, proceed normally
    return;
  }

  // Check if user has any registered MFA methods
  const mfaMethods = await getMfaMethods();
  const hasMfaMethods =
    mfaMethods.devices.length > 0 || mfaMethods.passkeys.length > 0;

  if (!hasMfaMethods) {
    // Prompt user to add an MFA method
    showMfaRegistrationPrompt();
  } else {
    // Prompt user to complete MFA challenge
    showMfaChallengePrompt();
  }
};

Protect sensitive actions

import { isUserMissingMfaAuth } from '@dynamic-labs-sdk/client';

const performSensitiveAction = async () => {
  if (isUserMissingMfaAuth()) {
    throw new Error('MFA authentication required for this action');
  }

  // Proceed with sensitive action
  await executeSensitiveOperation();
};

Conditional UI rendering

import { isUserMissingMfaAuth } from '@dynamic-labs-sdk/client';

const renderDashboard = () => {
  const needsMfaAuth = isUserMissingMfaAuth();

  if (needsMfaAuth) {
    return <MfaAuthenticationPrompt />;
  }

  return <FullDashboard />;
};

Listen for auth state changes

import {
  isUserMissingMfaAuth,
  onEvent
} from '@dynamic-labs-sdk/client';

// Listen for user changes and check MFA status
onEvent({
  event: 'userChanged',
  listener: ({ user }) => {
    if (!user) return;

    const needsMfaAuth = isUserMissingMfaAuth();

    if (needsMfaAuth) {
      console.log('MFA authentication required');
      showMfaPrompt();
    } else {
      console.log('MFA authentication complete');
      hideMfaPrompt();
    }
  },
});

How it works

The function checks if the user’s JWT token contains the requiresAdditionalAuth scope:

user.scope?.includes('requiresAdditionalAuth')

This scope is added by the Dynamic backend when:

• Session-based MFA is enabled and required
• The user has not yet completed an MFA challenge for the current session
• The user is required to set up MFA but hasn’t done so yet

Error handling

The function throws an error if the user is not logged in:

import { isUserMissingMfaAuth } from '@dynamic-labs-sdk/client';

try {
  const needsMfaAuth = isUserMissingMfaAuth();
} catch (error) {
  console.error('User not logged in:', error);
}

React

isUserMissingMfaAuth() is synchronous — call it directly during render. Pair it with useUser() so your component re-renders after MFA is completed:

import { isUserMissingMfaAuth } from '@dynamic-labs-sdk/client';
import { useUser } from '@dynamic-labs-sdk/react-hooks';

function MfaGate({ children }: { children: React.ReactNode }) {
  const { data: user } = useUser(); // re-renders on userChanged

  if (!user) return null;
  if (isUserMissingMfaAuth()) return <MfaChallenge />;

  return <>{children}</>;
}

Related

• checkUserScopes - Check if user has required scopes
• isPendingRecoveryCodesAcknowledgment - Check if recovery codes need acknowledgment
• Session-Based MFA - Configure session-based MFA
• Action-Based MFA - Configure action-based MFA
• MFA Overview - Learn about MFA