Step-Up Authentication

Business Accounts are in early access. See the overview for the model.

Most business account mutations require an elevated access token — a short-lived JWT scoped to a specific action. The regular session token is not enough. If the call proceeds without one, the backend returns a 403.

Which operations require step-up

Operation	Required scope
`addBusinessAccountSigner`	`business_account:signer:add`
`removeBusinessAccountSigner`	`business_account:signer:remove`
`addBusinessAccountMember`	`business_account:member:add`
`removeBusinessAccountMember`	`business_account:member:remove`
`updateBusinessAccountMemberRole`	`business_account:member:role:update`
`transferBusinessAccountOwnership`	`business_account:transfer_ownership`
`addWalletToBusinessAccount`	`business_account:link_wallet`
`removeBusinessAccountWallet`	`business_account:wallet:remove`

These do not require step-up: createBusinessAccount, getBusinessAccount, listBusinessAccounts, createWalletForBusinessAccount.

Check whether step-up is needed

checkStepUpAuth does a fast local check first — if a valid elevated token for the scope is already in state, it returns { isRequired: false } without a network round-trip. Only if a fresh token is needed does it call the backend.

import { checkStepUpAuth } from '@dynamic-labs-sdk/client';

const result = await checkStepUpAuth({ scope: 'business_account:signer:add' });

if (result.isRequired) {
  // Prompt the user to verify (see options below)
}

How to obtain an elevated token

Option 1 — MFA / passkey verify with `requestedScopes`

Pass requestedScopes when verifying with MFA, a passkey, or email OTP. The SDK parses the elevated token from the verify response and stores it automatically.

import { serverAuthenticatePasskey } from '@dynamic-labs-sdk/client';

await serverAuthenticatePasskey({
  requestedScopes: ['business_account:signer:add'],
});

The same requestedScopes parameter is available on authenticateTotpMfaDevice, verifyOTP, and signInWithSocialPopUp.

Option 2 — External auth assertion (server-side)

If your backend issues its own JWTs (registered via your environment’s JWKS URL), mint a short-lived JWT containing sub, scope, jti, and exp claims and pass it to requestExternalAuthElevatedToken.

import { requestExternalAuthElevatedToken } from '@dynamic-labs-sdk/client';

// externalJwt is signed by your backend and contains the scope claim
await requestExternalAuthElevatedToken({ externalJwt });

Option 3 — Step-up challenge flow

Use the credentials and defaultCredentialId from checkStepUpAuth to drive your own challenge UI, then pass the completed credential to a verify call with requestedScopes.

Putting it together

import { checkStepUpAuth, serverAuthenticatePasskey, addBusinessAccountSigner } from '@dynamic-labs-sdk/client';

const scope = 'business_account:signer:add';

// 1. Check if step-up is needed
const { isRequired } = await checkStepUpAuth({ scope });

// 2. If so, obtain the elevated token
if (isRequired) {
  await serverAuthenticatePasskey({ requestedScopes: [scope] });
}

// 3. Proceed — the SDK attaches the elevated token automatically
await addBusinessAccountSigner({
  businessAccountId,
  walletAccount,
  targetIdentity: { identifier: 'teammate@acme.com', identifierType: 'email' },
});

The SDK retrieves the stored elevated token and attaches it as x-dyn-elevated-access-token on the request. You do not pass the token manually.

Error handling

If the elevated token is missing or expired, the backend returns a 403. Catch it and prompt for re-verification:

import { APIError } from '@dynamic-labs-sdk/client';

try {
  await addBusinessAccountSigner({ ... });
} catch (error) {
  if (error instanceof APIError && error.status === 403) {
    // Step-up token missing or expired — re-verify
  }
}

Installation & Configuration

Chains & Networks

Authenticate

User & Session Management

Business Accounts

Wallets

Flow

Swaps

Funding & Onramp

Events

Building UI

Migrating from React

Extension Development

Step-Up Authentication

Which operations require step-up

Check whether step-up is needed

How to obtain an elevated token

Option 1 — MFA / passkey verify with `requestedScopes`

Option 2 — External auth assertion (server-side)

Option 3 — Step-up challenge flow

Putting it together

Error handling

​Which operations require step-up

​Check whether step-up is needed

​How to obtain an elevated token

​Option 1 — MFA / passkey verify with requestedScopes

​Option 2 — External auth assertion (server-side)

​Option 3 — Step-up challenge flow

​Putting it together

​Error handling

Which operations require step-up

Check whether step-up is needed

How to obtain an elevated token

Option 1 — MFA / passkey verify with `requestedScopes`

Option 2 — External auth assertion (server-side)

Option 3 — Step-up challenge flow

Putting it together

Error handling