Upgrading the API to 2026_04_01

Some API changes introduce breaking behavior. To prevent your integration from breaking unexpectedly, you control when to adopt new API behavior by setting a minimum API version in the dashboard. Go to Dashboard > Developers > API & SDK Keys to view and set your minimum API version. New environments default to the latest version. Existing environments remain on their current version until you opt in.

2026_04_01

Setting 2026_04_01 as your minimum version enables two security features:

Step-up authentication

Step-up authentication requires users to re-verify their identity before performing sensitive actions. Credential linking/unlinking and wallet export always require step-up verification. Wallet sign is optional and configurable.

Device registration

Device registration protects accounts from takeover by verifying users when they sign in from an unrecognized device. They receive an email verification link before being granted access. New users are registered automatically during signup with no extra friction.

Migrating from action-based MFA to step-up authentication

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)
Hook	`useMfa` / `useAuthenticatePasskeyMFA`	`useStepUpAuthentication`
Token type	Unscoped MFA token (`createMfaToken`)	Scoped elevated access token (`requestedScopes`)
Token handling	SDK-managed MFA token	SDK-managed elevated access token (scoped JWT)
Who can verify	Only users with MFA methods (TOTP/Passkey)	All users — MFA methods, email OTP, SMS OTP, wallet signature, or social OAuth
Scope	None — token accepted for any action	Bound to specific scopes (`wallet:export`, `wallet:sign`, `credential:link`, `credential:unlink`)
Expiration	Single-use, no time limit	Time-limited (5 min single-use, 10 min multi-use)

Dashboard changes

No dashboard changes are required for the migration itself. Your existing action-based MFA event configuration (Waas Export, Waas Refresh, WaaS Sign, WaaS Reshare) carries over. The key dashboard action is accepting the minimum API version at Dashboard > Developers > API & SDK Keys. Once set to 2026_04_01, the backend enforces step-up authentication on all sensitive operations. Make sure your code is updated before accepting the minimum version.

Code migration: before and after

Using Dynamic’s built-in UI

React
React Native
Flutter

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:

import { useStepUpAuthentication } from '@dynamic-labs/sdk-react-core';
import { TokenScope } from '@dynamic-labs/sdk-api-core';

const { isStepUpRequired, promptStepUpAuth } = useStepUpAuthentication();

if (await isStepUpRequired({ scope: TokenScope.Walletexport })) {
  await promptStepUpAuth({
    requestedScopes: [TokenScope.Walletexport],
  });
}

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

Before — client.ui.mfa.show with createMfaToken:

import { MFAAction } from '@dynamic-labs/sdk-api-core';

const isMfaRequired = await client.mfa.isRequiredForAction({
  mfaAction: MFAAction.WalletWaasExport,
});

if (isMfaRequired) {
  await client.ui.mfa.show({ createMfaToken: true });
}

await primaryWallet.exportWaasPrivateKey();

After — client.stepUpAuth.promptStepUpAuth with requestedScopes:

import { TokenScope } from '@dynamic-labs/sdk-api-core';

const isRequired = await client.stepUpAuth.isStepUpRequired({
  scope: TokenScope.Walletexport,
});

if (isRequired) {
  await client.stepUpAuth.promptStepUpAuth({
    requestedScopes: [TokenScope.Walletexport],
  });
}

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

Flutter did not have a built-in action-based MFA UI. Use promptStepUpAuth to add step-up verification:

import 'package:dynamic_sdk/dynamic_sdk.dart';

final isRequired = await DynamicSDK.instance.stepUpAuth
    .isStepUpRequired('wallet:export');

if (isRequired) {
  await DynamicSDK.instance.stepUpAuth.promptStepUpAuth(
    requestedScopes: ['wallet:export'],
  );
}

// Token is stored — SDK attaches it automatically
await performExport();

Headless TOTP

React
JavaScript
React Native
Flutter

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:

import { useStepUpAuthentication } from '@dynamic-labs/sdk-react-core';
import { TokenScope } from '@dynamic-labs/sdk-api-core';

const { isStepUpRequired, verifyTotpMfa } = useStepUpAuthentication();

if (await isStepUpRequired({ scope: TokenScope.Walletexport })) {
  await verifyTotpMfa({
    code: totpCode,
    requestedScopes: [TokenScope.Walletexport],
  });
}

Before — authenticateTotpMfaDevice with createMfaTokenOptions:

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

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

if (required) {
  await authenticateTotpMfaDevice({
    code: '123456',
    createMfaTokenOptions: { singleUse: true },
  });
}

After — same function with requestedScopes:

import { checkStepUpAuth, authenticateTotpMfaDevice } from '@dynamic-labs-sdk/client';
import { TokenScope } from '@dynamic-labs/sdk-api-core';

const { isRequired } = await checkStepUpAuth({ scope: TokenScope.Walletexport });

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

Before — client.mfa.authenticateDevice with createMfaToken:

import { MFAAction } from '@dynamic-labs/sdk-api-core';

const requires = await client.mfa.isRequiredForAction({
  mfaAction: MFAAction.WalletWaasExport,
});

if (requires) {
  await client.mfa.authenticateDevice({
    code: totpCode,
    createMfaToken: { singleUse: true },
  });
}

After — client.stepUpAuth.verifyTotpMfa with requestedScopes:

import { TokenScope } from '@dynamic-labs/sdk-api-core';

const isRequired = await client.stepUpAuth.isStepUpRequired({
  scope: TokenScope.Walletexport,
});

if (isRequired) {
  await client.stepUpAuth.verifyTotpMfa({
    code: totpCode,
    requestedScopes: [TokenScope.Walletexport],
  });
}

import 'package:dynamic_sdk/dynamic_sdk.dart';

final isRequired = await DynamicSDK.instance.stepUpAuth
    .isStepUpRequired('wallet:export');

if (isRequired) {
  await DynamicSDK.instance.stepUpAuth.verifyTotpMfa(
    code: totpCode,
    requestedScopes: ['wallet:export'],
  );
}

Headless Passkey

React
JavaScript
React Native
Flutter

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:

import { useStepUpAuthentication } from '@dynamic-labs/sdk-react-core';
import { TokenScope } from '@dynamic-labs/sdk-api-core';

const { isStepUpRequired, verifyPasskeyMfa } = useStepUpAuthentication();

if (await isStepUpRequired({ scope: TokenScope.Walletexport })) {
  await verifyPasskeyMfa({
    requestedScopes: [TokenScope.Walletexport],
  });
}

Before — authenticatePasskeyMFA with createMfaToken:

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

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

if (required) {
  await authenticatePasskeyMFA({
    createMfaToken: { singleUse: true },
  });
}

After — same function with requestedScopes:

import { checkStepUpAuth, authenticatePasskeyMFA } from '@dynamic-labs-sdk/client';
import { TokenScope } from '@dynamic-labs/sdk-api-core';

const { isRequired } = await checkStepUpAuth({ scope: TokenScope.Walletexport });

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

Before — client.passkeys.authenticateMFA with createMfaToken:

import { MFAAction } from '@dynamic-labs/sdk-api-core';

const requires = await client.mfa.isRequiredForAction({
  mfaAction: MFAAction.WalletWaasExport,
});

if (requires) {
  const passkeys = await client.passkeys.get();
  if (passkeys.length === 0) {
    await client.passkeys.register();
  }

  await client.passkeys.authenticateMFA({
    createMfaToken: { singleUse: false },
  });
}

After — client.stepUpAuth.verifyPasskeyMfa with requestedScopes:

import { TokenScope } from '@dynamic-labs/sdk-api-core';

const isRequired = await client.stepUpAuth.isStepUpRequired({
  scope: TokenScope.Walletexport,
});

if (isRequired) {
  await client.stepUpAuth.verifyPasskeyMfa({
    requestedScopes: [TokenScope.Walletexport],
  });
}

import 'package:dynamic_sdk/dynamic_sdk.dart';

final isRequired = await DynamicSDK.instance.stepUpAuth
    .isStepUpRequired('wallet:export');

if (isRequired) {
  await DynamicSDK.instance.stepUpAuth.verifyPasskeyMfa(
    requestedScopes: ['wallet:export'],
  );
}

Migration checklist

React
JavaScript
React Native
Flutter

Upgrade to React SDK 4.76.0 or later
Replace useMfa / useAuthenticatePasskeyMFA / usePromptMfaAuth with useStepUpAuthentication
Replace createMfaToken with requestedScopes using the appropriate TokenScope
Replace useIsMfaRequiredForAction with isStepUpRequired
Test the step-up flow end-to-end for each protected action
Accept the minimum API version 2026_04_01 in your dashboard

Upgrade to JavaScript SDK 0.24.1 or later
Replace isMfaRequiredForAction with checkStepUpAuth
Replace createMfaToken / createMfaTokenOptions with requestedScopes on authenticateTotpMfaDevice and authenticatePasskeyMFA
Test the step-up flow end-to-end for each protected action
Accept the minimum API version 2026_04_01 in your dashboard

Upgrade to React Native SDK 4.76.0 or later
Replace client.mfa.isRequiredForAction with client.stepUpAuth.isStepUpRequired
Replace client.mfa.authenticateDevice with client.stepUpAuth.verifyTotpMfa
Replace client.passkeys.authenticateMFA with client.stepUpAuth.verifyPasskeyMfa
Replace client.ui.mfa.show with client.stepUpAuth.promptStepUpAuth
Test the step-up flow end-to-end for each protected action
Accept the minimum API version 2026_04_01 in your dashboard

Upgrade to Flutter SDK 1.2.10 or later
Implement step-up checks with DynamicSDK.instance.stepUpAuth.isStepUpRequired
Add verification flows using promptStepUpAuth, verifyTotpMfa, or verifyPasskeyMfa
Test the step-up flow end-to-end for each protected action
Accept the minimum API version 2026_04_01 in your dashboard

For the full step-up authentication reference (all verification methods, scopes, token lifecycle), see Step-up authentication.

Action required

You must implement both features in your app before setting the minimum API version. Once enabled, the backend enforces these requirements immediately — users will see errors if your app doesn’t handle them. If you use Dynamic’s built-in widget UI (The Dynamic Widget with the React SDK, for example) you are all set, just upgrade to the latest version. If you have a headless integration, you need to build the verification UI yourself — start with the feature overviews, then check minimum SDK versions and per-SDK guides.

Feature overviews

Step-up authentication — how it works, verification methods, scopes, and SDK implementation guides
Device registration — how it works and SDK implementation guides

Minimum SDK versions

These minimum versions include support for step-up authentication and device registration. Implement both flows before raising your minimum API version.

SDK	Minimum version
React	`4.76.0`
React Native	`4.76.0`
JavaScript	`0.24.1`
Flutter	`1.2.10`
Kotlin	`1.0.8`
Swift	`1.0.11`

Implementation guides

SDK	Device registration	Step-up
React	Guide	Guide
React Native	Guide	Guide
JavaScript	Guide	Guide
Flutter	Overview	Guide
Kotlin	Overview	Overview
Swift	Overview	Overview

Getting Started

Going Live

Wallets

Chains & External Wallet Support

Payments

Earn

Agents

Authentication

Security

Rate Limits

Developer Dashboard

API Upgrades

Migrations

Troubleshooting

Upgrading the API to 2026_04_01

2026_04_01

Step-up authentication

Device registration

Migrating from action-based MFA to step-up authentication

What changed

Dashboard changes

Code migration: before and after

Using Dynamic’s built-in UI

Headless TOTP

Headless Passkey

Migration checklist

Action required

Feature overviews

Minimum SDK versions

Implementation guides

Getting Started

Going Live

Wallets

Chains & External Wallet Support

Payments

Earn

Agents

Authentication

Security

Rate Limits

Developer Dashboard

API Upgrades

Migrations

Troubleshooting

​2026_04_01

​Step-up authentication

​Device registration

​Migrating from action-based MFA to step-up authentication

​What changed

​Dashboard changes

​Code migration: before and after

​Using Dynamic’s built-in UI

​Headless TOTP

​Headless Passkey

​Migration checklist

​Action required

​Feature overviews

​Minimum SDK versions

​Implementation guides

2026_04_01

Step-up authentication

Device registration

Migrating from action-based MFA to step-up authentication

What changed

Dashboard changes

Code migration: before and after

Using Dynamic’s built-in UI

Headless TOTP

Headless Passkey

Migration checklist

Action required

Feature overviews

Minimum SDK versions

Implementation guides