Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt

Use this file to discover all available pages before exploring further.

This guide is only relevant if you previously used action-based MFA to protect sensitive wallet operations. If you didn’t, you can skip it.
If you previously used action-based MFA to protect sensitive wallet operations, step-up authentication replaces and extends that functionality. The core concept is the same — require users to re-verify before sensitive actions — but step-up auth adds scoped elevated access tokens, re-authentication methods for non-MFA users, and automatic token handling by the SDK.

​
What changed

Action-based MFA (before)Step-up authentication (after)
HookuseMfa / useAuthenticatePasskeyMFAuseStepUpAuthentication
Token typeUnscoped MFA token (createMfaToken)Scoped elevated access token (requestedScopes)
Token handlingSDK-managed MFA tokenSDK-managed elevated access token (scoped JWT)
Who can verifyOnly users with MFA methods (TOTP/Passkey)All users — MFA methods, email OTP, SMS OTP, wallet signature, or social OAuth
ScopeNone — token accepted for any actionBound to specific scopes (wallet:export, wallet:sign, credential:link, credential:unlink)
ExpirationSingle-use, no time limitTime-limited (5 min single-use, 10 min multi-use)

​
Dashboard changes

No dashboard changes are required — your existing action-based MFA event configuration (WaaS Export, WaaS Refresh, WaaS Sign, WaaS Reshare) carries over.
Make sure your code is fully updated before accepting the minimum API version at Dashboard > Developers > API & SDK Keys. Once set to 2026_04_01, the backend enforces step-up authentication immediately.

​
AI-assisted upgrade prompts

These prompts are designed for AI coding agents (Cursor, Claude Code, Copilot). Always review generated code before committing — agents can misread your project structure.For best results, install the Dynamic MCP in your agent so it can reference live documentation automatically. If you don’t have it installed, the prompts fall back to https://www.dynamic.xyz/docs/llms.txt.
Copy the prompt for your SDK and run it in your agent. 
I'm migrating my Dynamic SDK headless integration from action-based MFA to step-up authentication as part of the 2026_04_01 API upgrade.

If you have the Dynamic MCP installed, use it to reference the latest API.
Otherwise reference: https://www.dynamic.xyz/docs/llms.txt

In my codebase:
1. Find all usages of `useMfa`, `useAuthenticatePasskeyMFA`, and `usePromptMfaAuth`
2. Replace them with `useStepUpAuthentication` from `@dynamic-labs/sdk-react-core`
3. Replace all `createMfaToken` options with `requestedScopes` using the
   appropriate `TokenScope` from `@dynamic-labs/sdk-api-core`
4. Replace all `useIsMfaRequiredForAction` calls with `isStepUpRequired`
5. Do not modify any files outside of the auth flow

After making changes, summarize what was updated and flag anything that
needs manual review.

​
Code migration: before and after

The After examples include an else branch that falls through to legacy action-based MFA. It is only needed if some of your users already have legacy MFA enabled and you’re deploying the updated SDK before the 2026_04_01 API version is confirmed. Once both the SDK and the minimum API version are upgraded, the transitional else branches can be removed since they are no longer needed.

​
Using Dynamic’s built-in UI

Before — usePromptMfaAuth with createMfaToken:
    import { usePromptMfaAuth, useIsMfaRequiredForAction } from "@dynamic-labs/sdk-react-core";
    import { MFAAction } from '@dynamic-labs/sdk-api-core';

    const isMfaRequiredForAction = useIsMfaRequiredForAction();
    const promptMfaAuth = usePromptMfaAuth();

    const isMfaRequired = await isMfaRequiredForAction({
      mfaAction: MFAAction.WalletWaasExport,
    });

    if (isMfaRequired) {
      await promptMfaAuth({ createMfaToken: true });
    }

    await primaryWallet.exportWaasPrivateKey();
After — useStepUpAuthentication with requestedScopes. The else branch is only needed if some of your users already have legacy MFA enabled — it handles the window when the frontend is deployed before the 2026_04_01 API version is confirmed. Remove it once both the SDK and the minimum API version are upgraded:
    import {
      useStepUpAuthentication,
      usePromptMfaAuth,
      useIsMfaRequiredForAction,
    } from '@dynamic-labs/sdk-react-core';
    import { TokenScope, MFAAction } from '@dynamic-labs/sdk-api-core';

    const { isStepUpRequired, promptStepUpAuth } = useStepUpAuthentication();
    const promptMfaAuth = usePromptMfaAuth();
    const isMfaRequiredForAction = useIsMfaRequiredForAction();

    if (await isStepUpRequired({ scope: TokenScope.Walletexport })) {
      await promptStepUpAuth({
        requestedScopes: [TokenScope.Walletexport],
      });
    } else {
      // Transitional: 2026_04_01 API version not yet confirmed.
      // Legacy MFA prompt for users with an existing passkey / TOTP / device.
      const isMfaRequired = await isMfaRequiredForAction({
        mfaAction: MFAAction.WalletWaasExport,
      });
      if (isMfaRequired) {
        await promptMfaAuth({ createMfaToken: true });
      }
    }

    // Token is stored — SDK attaches it automatically
    await primaryWallet.exportWaasPrivateKey();

​
Headless TOTP

Before — useMfa with authenticateDevice and createMfaToken:
    import { useMfa, useIsMfaRequiredForAction } from "@dynamic-labs/sdk-react-core";
    import { MFAAction } from '@dynamic-labs/sdk-api-core';

    const { authenticateDevice } = useMfa();
    const isMfaRequiredForAction = useIsMfaRequiredForAction();

    const requires = await isMfaRequiredForAction({
      mfaAction: MFAAction.WalletWaasExport,
    });

    if (requires) {
      await authenticateDevice({
        code: totpCode,
        createMfaToken: { singleUse: true },
      });
    }
After — useStepUpAuthentication with verifyTotpMfa. The else branch is only needed if some of your users already have legacy MFA enabled — it handles the window before the 2026_04_01 API version is confirmed. Remove it once both the SDK and the minimum API version are upgraded:
    import {
      useStepUpAuthentication,
      useMfa,
      useIsMfaRequiredForAction,
    } from '@dynamic-labs/sdk-react-core';
    import { TokenScope, MFAAction } from '@dynamic-labs/sdk-api-core';

    const { isStepUpRequired, verifyTotpMfa } = useStepUpAuthentication();
    const { authenticateDevice } = useMfa();
    const isMfaRequiredForAction = useIsMfaRequiredForAction();

    if (await isStepUpRequired({ scope: TokenScope.Walletexport })) {
      await verifyTotpMfa({
        code: totpCode,
        requestedScopes: [TokenScope.Walletexport],
      });
    } else {
      // Transitional: 2026_04_01 API version not yet confirmed.
      // Legacy TOTP verification for users with an existing MFA device.
      const requires = await isMfaRequiredForAction({
        mfaAction: MFAAction.WalletWaasExport,
      });
      if (requires) {
        await authenticateDevice({
          code: totpCode,
          createMfaToken: { singleUse: true },
        });
      }
    }

​
Headless Passkey

Before — useAuthenticatePasskeyMFA with createMfaToken:
    import {
      useAuthenticatePasskeyMFA,
      useGetPasskeys,
      useIsMfaRequiredForAction,
      useRegisterPasskey,
    } from "@dynamic-labs/sdk-react-core";
    import { MFAAction } from '@dynamic-labs/sdk-api-core';

    const authenticatePasskeyMFA = useAuthenticatePasskeyMFA();
    const getPasskeys = useGetPasskeys();
    const registerPasskey = useRegisterPasskey();
    const isMfaRequiredForAction = useIsMfaRequiredForAction();

    const requires = await isMfaRequiredForAction({
      mfaAction: MFAAction.WalletWaasExport,
    });

    if (requires) {
      const passkeys = await getPasskeys();
      if (passkeys.length === 0) {
        await registerPasskey();
      }

      await authenticatePasskeyMFA({
        createMfaToken: { singleUse: false },
      });
    }
After — useStepUpAuthentication with verifyPasskeyMfa. The else branch is only needed if some of your users already have legacy MFA enabled — it handles the window before the 2026_04_01 API version is confirmed. Remove it once both the SDK and the minimum API version are upgraded:
    import {
      useStepUpAuthentication,
      useAuthenticatePasskeyMFA,
      useGetPasskeys,
      useRegisterPasskey,
      useIsMfaRequiredForAction,
    } from '@dynamic-labs/sdk-react-core';
    import { TokenScope, MFAAction } from '@dynamic-labs/sdk-api-core';

    const { isStepUpRequired, verifyPasskeyMfa } = useStepUpAuthentication();
    const authenticatePasskeyMFA = useAuthenticatePasskeyMFA();
    const getPasskeys = useGetPasskeys();
    const registerPasskey = useRegisterPasskey();
    const isMfaRequiredForAction = useIsMfaRequiredForAction();

    if (await isStepUpRequired({ scope: TokenScope.Walletexport })) {
      await verifyPasskeyMfa({
        requestedScopes: [TokenScope.Walletexport],
      });
    } else {
      // Transitional: 2026_04_01 API version not yet confirmed.
      // Legacy passkey MFA for users with an existing registered passkey.
      const requires = await isMfaRequiredForAction({
        mfaAction: MFAAction.WalletWaasExport,
      });
      if (requires) {
        const passkeys = await getPasskeys();
        if (passkeys.length === 0) {
          await registerPasskey();
        }
        await authenticatePasskeyMFA({
          createMfaToken: { singleUse: false },
        });
      }
    }

​
Migration checklist

  1. Upgrade to React SDK 4.76.0 or later
  2. Replace useMfa / useAuthenticatePasskeyMFA / usePromptMfaAuth with useStepUpAuthentication
  3. Replace createMfaToken with requestedScopes using the appropriate TokenScope
  4. Replace useIsMfaRequiredForAction with isStepUpRequired
  5. If you have existing legacy MFA users and you’re deploying the SDK update before accepting the new API version, keep the transitional else branch shown in each After example so those users still get prompted
  6. Test the step-up flow end-to-end for each protected action
  7. Accept the minimum API version 2026_04_01 in your dashboard
  8. Remove the transitional else branches
For the full step-up authentication reference (all verification methods, scopes, token lifecycle), see Step-up authentication.