Authenticator Apps

Authenticator apps provide a time-based one-time password (TOTP) that can be used for authentication.

Prerequisites

• You need to have the Dynamic Client initialized.
• You need to have the authenticator apps MFA enabled in your environment’s settings in the Dynamic developer console.

Registering a new TOTP device

Calling registerTotpMfaDevice will return a URI and a secret key for the TOTP device. You can use the URI to display a QR code to the user, so they can scan it with their authenticator app to get a TOTP code.

Unlike passkeys, registering a TOTP device will not automatically authenticate it, so you need to call authenticateTotpMfaDevice after registering a TOTP device for the user to complete an MFA challenge.

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

const register = async () => {
  const { uri, secret } = await registerTotpMfaDevice();
  console.log(uri, secret);
};

Doing MFA authentication with a TOTP code

Calling authenticateTotpMfaDevice will verify the TOTP code and complete the MFA challenge. The authentication will be successful if the user enters a valid TOTP code for the registered TOTP device.

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

const onLogin = async () => {
  await authenticateTotpMfaDevice({ code: '123456' });
};

With step-up authentication (recommended)

Pass requestedScopes to receive an elevated access token for sensitive actions:

import { exportWaasPrivateKey } from '@dynamic-labs-sdk/client/waas';
import {
  authenticateTotpMfaDevice,
  TokenScope,
} from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  await authenticateTotpMfaDevice({
    code: '123456',
    requestedScopes: [TokenScope.Walletexport],
  });

  // Elevated token is now stored — the SDK attaches it automatically
  await exportWaasPrivateKey(params);
};

With MFA token (deprecated)

createMfaTokenOptions is deprecated and will be removed in the next major version. Use requestedScopes instead. See migration guide.

import { exportWaasPrivateKey } from '@dynamic-labs-sdk/client/waas';
import { authenticateTotpMfaDevice } from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  await authenticateTotpMfaDevice({
    code: '123456',
    createMfaTokenOptions: { singleUse: true },
  });

  await exportWaasPrivateKey(params);
};

Deleting a TOTP device

Calling deleteMfaDevice will delete a TOTP device associated with the authenticated user.

To delete a TOTP device, you first need to get the user to perform an authentication challenge with that TOTP device, and then use the deleteMfaDevice function with that MFA token.

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

const deleteTotpDevice = async () => {
  // Authenticate with the TOTP device to be deleted
  // Replace '123456' with the actual TOTP code the user enters
  await authenticateTotpMfaDevice({
    code: '123456',
    createMfaTokenOptions: { singleUse: true },
  });

  // Get the MFA token from the dynamic client
  const mfaToken = dynamicClient.mfaToken;

  // Replace 'device-id' with the actual ID of the TOTP device you want to delete
  // Replace 'mfa-auth-token' with the actual MFA authentication token
  await deleteMfaDevice({ deviceId: 'device-id', mfaAuthToken: mfaToken });
};

Getting all registered TOTP devices for a user

Calling getMfaDevices will return all registered TOTP devices for the authenticated user. Currently, only one TOTP device is supported per user.

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

const getUserMfaDevices = async () => {
  const mfaDevices = await getMfaDevices();
  console.log(mfaDevices);
};

React

The TOTP flow requires multiple steps: register the device with useRegisterTotpMfaDevice (its data holds the URI/QR code), then verify with useAuthenticateTotpMfaDevice:

import {
  useAuthenticateTotpMfaDevice,
  useRegisterTotpMfaDevice,
} from '@dynamic-labs-sdk/react-hooks';
import { useState } from 'react';

function TotpEnrollment() {
  const [code, setCode] = useState('');

  const { mutate: registerDevice, data: registration } = useRegisterTotpMfaDevice();
  const { mutate: authenticateDevice, isSuccess: enrolled } = useAuthenticateTotpMfaDevice();

  if (enrolled) return <p>TOTP device enrolled successfully.</p>;

  return (
    <div>
      {!registration ? (
        <button onClick={() => registerDevice()}>Set Up Authenticator App</button>
      ) : (
        <form
          onSubmit={(e) => {
            e.preventDefault();
            authenticateDevice({ code });
          }}
        >
          <p>Scan this QR code with your authenticator app:</p>
          {/* render QR code from registration.uri using a QR library */}
          <input
            value={code}
            onChange={(e) => setCode(e.target.value)}
            placeholder="Enter 6-digit code"
            maxLength={6}
          />
          <button type="submit">Verify</button>
        </form>
      )}
    </div>
  );
}

Related functions

• Step-Up Authentication
• Passkeys
• Recovery Codes
• Overview
• Session-Based MFA
• Action-Based MFA