Skip to main content
If you use Bring Your Own Auth (BYOA), you can issue elevated access tokens directly from your backend without prompting the user for re-authentication or MFA. Your backend signs an assertion JWT and the SDK exchanges it for an elevated access token. This is useful when your backend has already verified the user’s identity through its own means (e.g., a session, an internal auth check, or a custom challenge) and you want to authorize a sensitive Dynamic operation without additional user friction. For concepts, scopes, and token lifecycle, see Step-up authentication overview.

​
Prerequisites

  • @dynamic-labs-sdk/client initialized
  • External auth (BYOA) configured with a JWKS URL in your dashboard
  • The user is already signed in via external auth

​
How it works

  1. Your backend creates an assertion JWT signed with the same key registered in your environment’s JWKS URL.
  2. The SDK sends this JWT to Dynamic’s backend, which validates the signature and issues an elevated access token.
  3. The elevated token is automatically stored in SDK state and attached to subsequent API calls — no manual token handling is needed.

​
Assertion JWT requirements

Your backend must sign a JWT with the following claims:
ClaimRequiredDescription
subYesThe user’s external user ID (must match the signed-in user)
scopeYesSpace-delimited scopes to request (e.g., "wallet:export")
jtiYesA unique token identifier (prevents replay attacks)
expYesExpiration time (Unix timestamp in seconds)
Example payload: 
{
  "sub": "user-123",
  "scope": "wallet:export",
  "jti": "unique-request-id-abc",
  "exp": 1711900000
}
The JWT must be signed using the same algorithm and key that corresponds to your environment’s JWKS URL.

​
Usage

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

// 1. Get the assertion JWT from your backend
const { jwt } = await fetch('/api/step-up', {
  method: 'POST',
  body: JSON.stringify({ action: 'wallet:export' }),
}).then((res) => res.json());

// 2. Exchange it for an elevated access token
await requestExternalAuthElevatedToken({ externalJwt: jwt });

// 3. Proceed — the SDK attaches the token to the relevant API call
await performExport();

​
Combining with checkStepUpAuth

You can use checkStepUpAuth to determine whether step-up is required before calling your backend: 
import {
  checkStepUpAuth,
  requestExternalAuthElevatedToken,
} from '@dynamic-labs-sdk/client';
import { TokenScope } from '@dynamic-labs/sdk-api-core';

const exportPrivateKey = async () => {
  const { isRequired } = await checkStepUpAuth({
    scope: TokenScope.Walletexport,
  });

  if (isRequired) {
    // Get assertion JWT from your backend
    const { jwt } = await fetchAssertionJwt('wallet:export');

    // Exchange for elevated access token
    await requestExternalAuthElevatedToken({ externalJwt: jwt });
  }

  // Proceed with the operation
  await performExport();
};

​
When to use external auth vs. other methods

ApproachBest for
External authBYOA setups where your backend controls identity verification. No user interaction needed on the client.
Re-auth / MFAWhen you want Dynamic to handle user verification (OTP, passkey, TOTP, etc.)
Both approaches produce the same elevated access token and are stored and consumed identically by the SDK.