Action-Based MFA

Action-Based MFA requires users to verify their identity for sensitive actions like transactions. By default, we only require action-based MFA once the user already has a MFA method registered.

Dashboard Setup

Configure Action-Based MFA in the dashboard before implementing in your application. See End-User MFA Configuration - Action-Based MFA for dashboard setup instructions.

Events that trigger Action-Based MFA

• Waas Export - When exporting a private key on an MPC wallet.
• Waas Refresh - When a wallet is delegated, or when a user claims a pregenerated MPC wallet for the first time.
• WaaS Sign - When any signature is performed i.e. a message, a transaction, typed data, authorization, etc.
• WaaS Reshare - When a wallet is approved or revoked from delegated access and the user next signs in.

Using step-up authentication (recommended)

Use requestedScopes to receive elevated access tokens instead of legacy MFA tokens. This is the recommended approach and will be required in the next major version.

TOTP

import {
  isMfaRequiredForAction,
  authenticateTotpMfaDevice,
  MFAAction,
} from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  const required = await isMfaRequiredForAction({ mfaAction: MFAAction.WalletWaasExport });

  if (required) {
    await authenticateTotpMfaDevice({
      code: '123456',
      requestedScopes: ['wallet:export'],
    });
  }

  // Elevated token is now stored — the SDK attaches it automatically
  await exportWaasPrivateKey(params);
};

Passkey

import {
  isMfaRequiredForAction,
  authenticatePasskeyMFA,
  MFAAction,
} from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  const required = await isMfaRequiredForAction({ mfaAction: MFAAction.WalletWaasExport });

  if (required) {
    await authenticatePasskeyMFA({
      requestedScopes: ['wallet:export'],
    });
  }

  // Elevated token is now stored — the SDK attaches it automatically
  await exportWaasPrivateKey(params);
};

For a complete guide on step-up authentication including all verification methods, see Step-Up Authentication.

Using MFA tokens (deprecated)

createMfaToken and createMfaTokenOptions are deprecated and will be removed in the next major version. Use requestedScopes instead. See migration guide.

TOTP

import { isMfaRequiredForAction, authenticateTotpMfaDevice, MFAAction } from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  const required = await isMfaRequiredForAction({ mfaAction: MFAAction.WalletWaasExport });
  if (required) {
    await authenticateTotpMfaDevice({ code: '123456', createMfaTokenOptions: { singleUse: true } });
  }
  await exportWaasPrivateKey(params);
};

Passkey

import { isMfaRequiredForAction, authenticatePasskeyMFA, MFAAction } from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  const required = await isMfaRequiredForAction({ mfaAction: MFAAction.WalletWaasExport });
  if (required) {
    await authenticatePasskeyMFA({ createMfaToken: { singleUse: true } });
  }
  await exportWaasPrivateKey(params);
};