Upgrading the API to 2026_04_01

Dynamic lets you opt into API changes on your own schedule. Not all updates are backwards compatible, so setting a minimum API version in the dashboard gives you control over when new behavior applies to your integration.

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 unlocks two security features:

• 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 — protects accounts from takeover and phishing attacks 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.

About device registration

Device registration is optional and disabled by default. Upgrading to 2026_04_01 does not turn it on — you control rollout from the Dynamic Dashboard under your environment’s security settings.

Key things to know before enabling it:

• Optional, off by default. The default is false. Nothing changes for your users until you enable it in the dashboard.
• Phishing protection via domain allow-listing. The verification email’s redirect URL is restricted to the domains you’ve allow-listed for your environment (the same CORS allow-list Dynamic enforces for browser requests). An attacker hosting a phishing site on a domain outside that list cannot have the verification link redirect to their site, so they cannot complete device registration even if they’ve harvested the user’s credentials.
• Not compatible with in-app wallet browsers. The verification link opens in the device’s default browser, so users who sign in from inside an in-app wallet browser (for example, MetaMask, Trust Wallet, Rainbow, or Coinbase Wallet) cannot complete verification. Leave device registration disabled if your app expects users on these surfaces.

Action required

If you plan to enable device registration or use step-up authentication, 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.

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	Guide	Guide
Kotlin	Guide	Guide
Swift	Guide	Guide

Widget UI

If you use Dynamic’s built-in widget UI (e.g. the Dynamic Widget with the React SDK), you’re all set — just upgrade to the minimum SDK version above. No additional UI work required.

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.

Install the Dynamic MCP below so your agent can reference live documentation automatically. If you don’t have it installed, the prompts fall back to https://www.dynamic.xyz/docs/llms.txt.

Cursor

Click here to add the MCP to Cursor.

Claude Code

claude mcp add --transport http dynamic https://www.dynamic.xyz/docs/mcp

Codex

codex mcp add dynamic --url https://www.dynamic.xyz/docs/mcp

Other

If your editor or agent supports remote HTTP MCP, add a server that points at https://www.dynamic.xyz/docs/mcp. The exact steps depend on the product; use its MCP documentation for URL-based or HTTP transport setup.

These steps are only required for headless integrations. If you use the Dynamic Widget, both step-up authentication and device registration UI are handled automatically — skip this section.

Step 1: Scaffold step-up authentication screen

React

I need to add step-up authentication to my Dynamic SDK headless
React integration 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 where sensitive actions occur — wallet export, wallet sign,
   credential linking and unlinking
2. Before each sensitive action, add a check using `isStepUpRequired`
   from `useStepUpAuthentication` in `@dynamic-labs/sdk-react-core`
3. If required, call `promptStepUpAuth` with the appropriate `TokenScope`
   from `@dynamic-labs/sdk-api-core`:
   - Wallet export: `TokenScope.Walletexport`
   - Wallet sign: `TokenScope.Walletsign`
   - Credential link: `TokenScope.Credentiallink`
   - Credential unlink: `TokenScope.Credentialunlink`
4. The SDK stores and attaches the token automatically — no manual
   token handling needed
5. Do not modify any files outside of the auth flow

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

JavaScript

I need to add step-up authentication to my Dynamic SDK headless
JavaScript integration 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 where sensitive actions occur — wallet export, wallet sign,
   credential linking and unlinking
2. Before each sensitive action, add a check using `checkStepUpAuth`
   from `@dynamic-labs-sdk/client` with the appropriate scope:
   - Wallet export: `TokenScope.Walletexport`
   - Wallet sign: `TokenScope.Walletsign`
   - Credential link: `TokenScope.Credentiallink`
   - Credential unlink: `TokenScope.Credentialunlink`
3. If required, call the appropriate verification method:
   - TOTP: `authenticateTotpMfaDevice` with `requestedScopes`
   - Passkey: `authenticatePasskeyMFA` with `requestedScopes`
4. The SDK stores and attaches the token automatically — no manual
   token handling needed
5. Do not modify any files outside of the auth flow

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

React Native

I need to add step-up authentication to my Dynamic SDK headless
React Native integration 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 where sensitive actions occur — wallet export, wallet sign,
   credential linking and unlinking
2. Before each sensitive action, add a check using:
   `client.stepUpAuth.isStepUpRequired` with the appropriate scope:
   - Wallet export: `TokenScope.Walletexport`
   - Wallet sign: `TokenScope.Walletsign`
   - Credential link: `TokenScope.Credentiallink`
   - Credential unlink: `TokenScope.Credentialunlink`
3. If required, call the appropriate method:
   - `client.stepUpAuth.promptStepUpAuth` — let SDK pick the method
   - `client.stepUpAuth.verifyTotpMfa` — TOTP verification
   - `client.stepUpAuth.verifyPasskeyMfa` — Passkey verification
4. The SDK stores and attaches the token automatically — no manual
   token handling needed
5. Do not modify any files outside of the auth flow

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

Flutter

I need to add step-up authentication to my Dynamic SDK headless
Flutter integration 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 where sensitive actions occur — wallet export, wallet sign,
   credential linking and unlinking
2. Before each sensitive action, add a check using:
   DynamicSDK.instance.stepUpAuth.isStepUpRequired(scope)
   with the appropriate scope string:
   'wallet:export', 'wallet:sign', 'credential:link', 'credential:unlink'
3. If required, call the appropriate method:
   - DynamicSDK.instance.stepUpAuth.promptStepUpAuth(requestedScopes)
   - DynamicSDK.instance.stepUpAuth.verifyTotpMfa
   - DynamicSDK.instance.stepUpAuth.verifyPasskeyMfa
4. The SDK stores and attaches the token automatically — no manual
   token handling needed
5. Do not modify any files outside of the auth flow

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

Kotlin

I need to add step-up authentication to my Dynamic SDK headless Kotlin integration 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 where sensitive actions occur — wallet export, wallet sign,
   credential linking and unlinking
2. Before each sensitive action, add a check using:
   sdk.stepUpAuth.isStepUpRequired(scope)
   with the appropriate scope string:
   'wallet:export', 'wallet:sign', 'credential:link', 'credential:unlink'
3. If required, call the appropriate method:
   - sdk.stepUpAuth.promptStepUpAuth(requestedScopes) — let SDK decide
   - sdk.stepUpAuth.verifyTotpMfa(code, deviceId, requestedScopes)
   - sdk.stepUpAuth.verifyPasskeyMfa(requestedScopes)
   - sdk.stepUpAuth.verifyOtp(verificationToken, requestedScopes)
4. The SDK stores and attaches the token automatically — no manual
   token handling needed
5. Do not modify any files outside of the auth flow

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

Swift

I need to add step-up authentication to my Dynamic SDK headless
Swift integration 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 where sensitive actions occur — wallet export, wallet sign,
   credential linking and unlinking
2. Before each sensitive action, add a check using:
   sdk.stepUpAuth.isStepUpRequired(scope:)
   with the appropriate scope string:
   'wallet:export', 'wallet:sign', 'credential:link', 'credential:unlink'
3. If required, call the appropriate method:
   - sdk.stepUpAuth.promptStepUpAuth(requestedScopes:) — let SDK decide
   - sdk.stepUpAuth.verifyTotpMfa(code:deviceId:requestedScopes:)
   - sdk.stepUpAuth.verifyPasskeyMfa(requestedScopes:)
   - sdk.stepUpAuth.verifyOtp(verificationToken:requestedScopes:)
4. The SDK stores and attaches the token automatically — no manual
   token handling needed
5. Do not modify any files outside of the auth flow

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

---

Step 2: Scaffold device registration screen

React

I need to add a device registration screen to my Dynamic SDK headless
React integration 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 where I handle the authentication flow and user state
2. Add a check for device registration using `isDeviceRegistrationRequired`
   from `@dynamic-labs-sdk/client` alongside `useDynamicClient`
3. If registration is required, render a "Check your email" screen —
   the SDK sends the verification link automatically, no additional API call needed
4. Wire up the following events using `useDynamicEvents`:
   - `deviceRegistrationCompleted` — user verified in this tab, proceed to app
   - `deviceRegistrationCompletedInAnotherTab` — user clicked link in another tab, update UI
5. Do not modify any files outside of the auth flow

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

JavaScript

I need to add a device registration flow to my Dynamic SDK headless
JavaScript integration 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. On app load, add a redirect check using `detectDeviceRegistrationRedirect`
   from `@dynamic-labs-sdk/client`
2. If the redirect is detected, call `getDeviceRegistrationTokenFromUrl`
   to extract the token and pass it to `completeDeviceRegistration`
3. Before sensitive auth flows, check `isDeviceRegistrationRequired` —
   if true, render a "Check your email" screen
   The SDK sends the verification link automatically, no additional API call needed
4. Do not modify any files outside of the auth flow

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

React Native

I need to add a device registration screen to my Dynamic SDK headless
React Native integration 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 where I handle the authentication flow and user state
2. Add a check using `client.deviceRegistration.isRequired()`
3. If required, call `client.deviceRegistration.handle()` and render
   a "Check your email" screen — the SDK sends the verification link automatically
4. Handle the completion event to navigate the user forward once verified
5. Do not modify any files outside of the auth flow

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

Flutter

I need to add a device registration screen to my Dynamic SDK headless
Flutter integration 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 where I handle the authentication flow and user state
2. Add a check using `DynamicSDK.instance.deviceRegistration.isRequired()`
3. If required, call `DynamicSDK.instance.deviceRegistration.handle()`
   and render a "Check your email" screen —
   the SDK sends the verification link automatically
4. Handle the completion callback to navigate the user forward once verified
5. Do not modify any files outside of the auth flow

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

Kotlin

I need to add a device registration screen to my Dynamic SDK headless
Kotlin integration 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 where I handle the authentication flow and user state
2. Add a one-time check using `sdk.deviceRegistration.isDeviceRegistrationRequired`
3. For reactive UI, observe the flow:
   `sdk.deviceRegistration.isDeviceRegistrationRequiredChanges`
4. If registration is required, render a DeviceRegistrationBanner or
   TrustedDevicesScreen composable —
   the SDK sends the verification email automatically
5. Do not modify any files outside of the auth flow

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

Swift

I need to add a device registration screen to my Dynamic SDK headless
Swift integration 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 where I handle the authentication flow and user state
2. Add a one-time check using `sdk.deviceRegistration.isDeviceRegistrationRequired`
3. For reactive UI, observe as an async stream:
   `sdk.deviceRegistration.isDeviceRegistrationRequiredChanges`
4. If registration is required, render a DeviceRegistrationBanner or
   TrustedDevicesView —
   the SDK sends the verification email automatically
5. Do not modify any files outside of the auth flow

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

---

Headless integrations

If you have an existing headless integration, you only need to implement two new screens introduced in 2026_04_01. See the implementation guides above for your SDK’s step-up authentication and device registration guides.

---

Migrating from action-based MFA to step-up authentication

This section is only relevant if you previously used action-based MFA to protect sensitive wallet operations. If you didn’t, you can skip this.

See the full MFA migration guide.