Passkeys

Passkeys use cryptographic key pairs stored on the user’s device. Authentication happens with a biometric check (such as Face ID, Touch ID, or a fingerprint scan) or a local device PIN. This makes passkeys both safer—since they can’t be phished or reused—and easier to use, since users don’t need to remember or type credentials.

Prerequisites

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

Registering a new passkey

Calling registerPasskey will prompt the user to register a new passkey in their device and register it in the Dynamic server, so next time the user can complete an MFA challenge with it or even sign-in with it if enabled in the environment’s settings.

Registering a passkey will automatically authenticate it, so you don’t need to call authenticatePasskeyMFA after registering a passkey.

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

const register = async () => {
  await registerPasskey();
};

Doing MFA authentication with a passkey

Calling authenticatePasskeyMFA will prompt the user to authenticate with a passkey in their device and complete an MFA challenge. The authentication will be successful if the user authenticates with the passkey in their device and it gets validated in the Dynamic server.

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

const onLogin = async () => {
  await authenticatePasskeyMFA();
};

To authenticate with a passkey that was registered on a related domain, pass that domain as relatedOriginRpId. This lets users complete MFA with passkeys they created before your domain changed. See Signing in with a passkey from a related domain for the required .well-known/webauthn setup on the related domain.

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

await authenticatePasskeyMFA({ relatedOriginRpId: 'old.example.com' });

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 { authenticatePasskeyMFA, TokenScope } from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  await authenticatePasskeyMFA({
    requestedScopes: [TokenScope.Walletexport],
  });

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

With MFA token (deprecated)

createMfaToken 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 { authenticatePasskeyMFA } from '@dynamic-labs-sdk/client';

const onExportPrivateKeyClick = async () => {
  await authenticatePasskeyMFA({
    createMfaToken: { singleUse: true },
  });

  await exportWaasPrivateKey(params);
};

Deleting a passkey

Calling deletePasskey will delete a passkey from the Dynamic server.

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

const handleDeletePasskey = async () => {
  // Replace 'passkey-id' with the actual ID of the passkey you want to delete
  await deletePasskey({passkeyId: 'passkey-id'});
};

Getting all registered passkeys for a user

Calling getPasskeys will return all registered passkeys for the authenticated user.

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

const getUserPasskeys = async () => {
  const passkeys = await getPasskeys();
  console.log(passkeys);
};

React

useGetPasskeys fetches the list. Mutations like useRegisterPasskey and useDeletePasskey automatically refetch the passkey list on success, so the UI stays in sync without manual intervention:

import { TokenScope } from '@dynamic-labs-sdk/client';
import {
  useAuthenticatePasskeyMFA,
  useDeletePasskey,
  useGetPasskeys,
  useRegisterPasskey,
} from '@dynamic-labs-sdk/react-hooks';

function PasskeyManager() {
  const { data: passkeys = [] } = useGetPasskeys();
  const { mutate: registerPasskey } = useRegisterPasskey();
  const { mutate: deletePasskey } = useDeletePasskey();

  return (
    <div>
      <button onClick={() => registerPasskey()}>Register New Passkey</button>
      <ul>
        {passkeys.map((p) => (
          <li key={p.id}>
            {p.alias ?? p.id}
            <button onClick={() => deletePasskey({ passkeyId: p.id })}>Delete</button>
          </li>
        ))}
      </ul>
    </div>
  );
}

function PasskeyMfaButton() {
  const { mutate: authenticatePasskeyMFA } = useAuthenticatePasskeyMFA();

  return (
    <button
      onClick={() =>
        authenticatePasskeyMFA({ requestedScopes: [TokenScope.Walletexport] })
      }
    >
      Authenticate with Passkey
    </button>
  );
}

Related functions

• Step-Up Authentication
• Signing in with a Passkey
• Authenticator Apps
• Recovery Codes
• Overview
• Session-Based MFA
• Action-Based MFA