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 an MFA method registered.

Dashboard Setup

Configure Action-Based MFA in the developer console 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,
  TokenScope,
} from '@dynamic-labs-sdk/client';
import { exportWaasPrivateKey } from '@dynamic-labs-sdk/client/waas';

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

  if (required) {
    await authenticateTotpMfaDevice({
      code: '123456',
      requestedScopes: [TokenScope.Walletexport],
    });
  }

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

Passkey

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

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

  if (required) {
    await authenticatePasskeyMFA({
      requestedScopes: [TokenScope.Walletexport],
    });
  }

  // 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.

React

In React, use useAuthenticateTotpMfaDevice for the MFA challenge and call the one-shot isMfaRequiredForAction check directly inside your handler before the sensitive operation:

import { exportWaasPrivateKey } from '@dynamic-labs-sdk/client/waas';
import {
  isMfaRequiredForAction,
  MFAAction,
  TokenScope,
} from '@dynamic-labs-sdk/client';
import { useAuthenticateTotpMfaDevice } from '@dynamic-labs-sdk/react-hooks';
import { useState } from 'react';

function ExportKeyButton() {
  const [code, setCode] = useState('');
  const [needsMfa, setNeedsMfa] = useState(false);

  const { mutate: authenticateTotpMfaDevice } = useAuthenticateTotpMfaDevice();

  const handleExport = async () => {
    const required = await isMfaRequiredForAction({ mfaAction: MFAAction.WalletWaasExport });
    if (required) {
      setNeedsMfa(true);
      return;
    }
    await exportWaasPrivateKey(params);
  };

  const handleMfaSubmit = () => {
    authenticateTotpMfaDevice(
      { code, requestedScopes: [TokenScope.Walletexport] },
      {
        onSuccess: () => {
          setNeedsMfa(false);
          exportWaasPrivateKey(params);
        },
      }
    );
  };

  if (needsMfa) {
    return (
      <div>
        <input value={code} onChange={(e) => setCode(e.target.value)} placeholder="Authenticator code" />
        <button onClick={handleMfaSubmit}>Confirm</button>
      </div>
    );
  }

  return <button onClick={handleExport}>Export private key</button>;
}

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';
import { exportWaasPrivateKey } from '@dynamic-labs-sdk/client/waas';

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';
import { exportWaasPrivateKey } from '@dynamic-labs-sdk/client/waas';

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