User Passkey Management

The UserPasskeyManagement component lets users enroll and revoke passkeys in a single card-based interface using the My Account API and requires no props to render. The component renders a list of enrolled passkeys, a button to add a new passkey, and a revoke option.

Prerequisites

To enable passkey support:

Configure a custom domain on your Auth0 tenant. Passkeys require a custom domain.
Enable passkeys on your Auth0 database connection. To learn how to enable passkeys in your Auth0 tenant, read Configure Passkeys.
Match origin. The relying party id must equal your application’s domain or be a registrable parent of it. To learn more, read Relying party ID for Passkeys
Ensure your application uses HTTPS. WebAuthn requires that your application is served over HTTPS.
Install and configure universal components in your application. To install and configure universal components, read Build Account Security UI.

Configure your application

Select your framework to configure environment variables and universal components.

React (SPA)
Next.js (RWA)
shadcn

Install the component

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

npm install @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form and @tanstack/react-query are peer dependencies. The command also installs the @auth0/universal-components-core dependency for shared utilities and Auth0 integration.

Get started

import { UserPasskeyManagement } from "@auth0/universal-components-react";

export function SecurityPage() {
  return <UserPasskeyManagement />;
}

Components are always imported from the root entry @auth0/universal-components-react, regardless of framework.
Only the Auth0ComponentProvider component uses a framework-specific subpath: /spa for React applications, /rwa for Next.js applications.

Full integration example

import React from "react";
import { UserPasskeyManagement } from "@auth0/universal-components-react";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserPasskeyManagement
        addAction={{
          onAfter: () => {
            analytics.track("Passkey Enrolled");
          },
        }}
        revokeAction={{
          onBefore: (passkey) =>
            window.confirm(`Remove passkey "${passkey.name}"?`),
          onAfter: (passkey) => {
            analytics.track("Passkey Revoked", { passkeyId: passkey.id });
          },
        }}
        customMessages={{
          header: {
            title: "Passkeys",
            description: "Sign in faster and more securely without a password.",
          },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Install the component

pnpm add @auth0/universal-components-react react-hook-form @tanstack/react-query

npm install @auth0/universal-components-react react-hook-form @tanstack/react-query

react-hook-form and @tanstack/react-query are peer dependencies. The command also installs the @auth0/universal-components-core dependency for shared utilities and Auth0 integration.

Get started

app/security/passkeys/page.tsx

"use client";

import { UserPasskeyManagement } from "@auth0/universal-components-react";

export default function PasskeysPage() {
  return <UserPasskeyManagement />;
}

Full integration example

app/security/passkeys/page.tsx

"use client";

import { UserPasskeyManagement } from "@auth0/universal-components-react";
import { analytics } from "@/lib/analytics";

export default function PasskeysPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserPasskeyManagement
        addAction={{
          onAfter: () => {
            analytics.track("Passkey Enrolled");
          },
        }}
        revokeAction={{
          onAfter: (passkey) => {
            analytics.track("Passkey Revoked", { passkeyId: passkey.id });
          },
        }}
        customMessages={{
          header: {
            title: "Passkeys",
            description: "Sign in faster and more securely without a password.",
          },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

Install the component

npx shadcn@latest add https://auth0-universal-components.vercel.app/r/my-account/user-passkey-management.json

The install command adds the component source into src/components/auth0/my-account/ along with all UI dependencies and the @auth0/universal-components-core dependency for shared utilities and Auth0 integration.

Get started

import { UserPasskeyManagement } from "@/components/auth0/my-account/user-passkey-management";

export function SecurityPage() {
  return <UserPasskeyManagement />;
}

Full integration example

import React from "react";
import { UserPasskeyManagement } from "@/components/auth0/my-account/user-passkey-management";
import { Auth0Provider } from "@auth0/auth0-react";
import { Auth0ComponentProvider } from "@auth0/universal-components-react/spa";
import { analytics } from "./lib/analytics";

function SecurityPage() {
  return (
    <div className="max-w-3xl mx-auto p-6">
      <UserPasskeyManagement
        addAction={{
          onAfter: () => {
            analytics.track("Passkey Enrolled");
          },
        }}
        revokeAction={{
          onBefore: (passkey) =>
            window.confirm(`Remove passkey "${passkey.name}"?`),
          onAfter: (passkey) => {
            analytics.track("Passkey Revoked", { passkeyId: passkey.id });
          },
        }}
        customMessages={{
          header: {
            title: "Passkeys",
            description: "Sign in faster and more securely without a password.",
          },
        }}
        styling={{
          variables: {
            light: { "--color-primary": "#4f46e5" },
            dark: { "--color-primary": "#818cf8" },
          },
        }}
      />
    </div>
  );
}

export default function App() {
  const domain = "YOUR_TENANT_DOMAIN.auth0.com";
  const clientId = "YOUR_CLIENT_ID";

  return (
    <Auth0Provider
      domain={domain}
      clientId={clientId}
      authorizationParams={{ redirect_uri: window.location.origin }}
      interactiveErrorHandler="popup"
    >
      <Auth0ComponentProvider domain={domain}>
        <SecurityPage />
      </Auth0ComponentProvider>
    </Auth0Provider>
  );
}

Props

Display props

Display props control how the component renders without affecting its behavior.

Prop	Type	Default	Description
`hideHeader`	`boolean`	`false`	Hide the page-level header (title and description). The section card with the passkey list is always shown.

Action props

Action props let you hook into the component’s lifecycle events and trigger or cancel operations.

Prop	Type	Description
`addAction`	`ComponentAction<void>`	Lifecycle hooks for the add-passkey flow. Set `disabled: true` to hide the add button.
`revokeAction`	`ComponentAction<Passkey>`	Lifecycle hooks for the revoke-passkey flow. Set `disabled: true` to hide the revoke option.
`onFetch`	`() => void`	Triggered after the passkey list is successfully loaded.

addAction Controls the add a passkey flow. onBefore triggers before the browser WebAuthn prompt is shown; return false to cancel (for example, to enforce a passkey limit). onAfter triggers after the new passkey is saved.

disabled hide the “Add passkey” button.
onBefore() runs before the WebAuthn enrollment ceremony. Return false to cancel.
onAfter() runs after the passkey is successfully registered. Use this to refresh session state or send analytics.

<UserPasskeyManagement
  addAction={{
    onBefore: () => {
      if (passkeys.length >= 5) {
        toast.error("You can register a maximum of 5 passkeys.");
        return false;
      }
      return true;
    },
    onAfter: () => {
      analytics.track("Passkey Enrolled");
    },
  }}
/>

revokeAction Controls the revoke a passkey flow. onBefore runs before the built-in confirmation modal is shown, so you can cancel the flow before the user sees the modal. onAfter triggers after the passkey is deleted from the account.

disabled hides the revoke option from the passkey actions menu.
onBefore(passkey) runs before the revoke API call. Receives the Passkey object. Return false to cancel.
onAfter(passkey) runs after the passkey is successfully revoked. Receives the revoked Passkey object.

<UserPasskeyManagement
  revokeAction={{
    onAfter: (passkey) => {
      auditLog.record({ action: "passkey_revoked", passkeyId: passkey.id });
    },
  }}
/>

onFetch Triggers after the passkey list is successfully loaded on mount. Use this to show or hide adjacent UI that depends on whether the user has any registered passkeys.

<UserPasskeyManagement
  onFetch={() => {
    setPasskeysLoaded(true);
  }}
/>

To render the list read-only, set disabled: true on both actions:

<UserPasskeyManagement
  addAction={{ disabled: true }}
  revokeAction={{ disabled: true }}
/>

Customize props

Customization props let you adapt copy and styling without modifying source code.

Prop	Type	Description
`customMessages`	`Partial<UserPasskeyManagementMessages>`	Override default UI text and translations.
`styling`	`ComponentStyling<UserPasskeyManagementClasses>`	CSS variables and class overrides.

customMessages Customize all text and translations. Every field is optional.

Available Messages

header—title, description (page-level header; hidden when hideHeader is true)
Top-level card—section_title, enabled (badge shown when passkeys are enrolled), no_passkeys (empty state message), add_passkey (add button label)
List items—created_at (use ${date} as placeholder), last_used (use ${date} as placeholder)
Actions—actions.revoke (label in the per-passkey actions menu)
Success toasts—success.add, success.revoke
Revoke modal—modals.revoke.title, modals.revoke.consent (use <bold>${name}</bold> to bold the passkey name), modals.revoke.cancel, modals.revoke.confirm

<UserPasskeyManagement
  customMessages={{
    header: {
      title: "Passkeys",
      description: "Sign in faster and more securely without a password.",
    },
    section_title: "Your passkeys",
    no_passkeys: "No passkeys registered yet.",
    add_passkey: "Add a passkey",
    created_at: "Added ${date}",
    last_used: "Last used ${date}",
    success: {
      add: "Passkey registered successfully.",
      revoke: "Passkey removed.",
    },
    modals: {
      revoke: {
        title: "Remove passkey?",
        consent: "This will permanently remove <bold>${name}</bold>.",
        cancel: "Cancel",
        confirm: "Remove",
      },
    },
  }}
/>

Customize style Customize appearance with CSS variables and class overrides. Supports light/dark themes.

Available Styling Options

Variables—CSS custom properties

common Applied to both themes
light Light mode only
dark Dark mode only

Class overrides

UserPasskeyManagement-root the outer card container wrapping the passkey list
UserPasskeyManagement-item each individual passkey row card
PasskeyActionModal-modalContent the revoke confirmation modal content area

<UserPasskeyManagement
  styling={{
    variables: {
      light: { "--color-primary": "#4f46e5" },
      dark: { "--color-primary": "#818cf8" },
    },
    classes: {
      "UserPasskeyManagement-root": "rounded-2xl shadow-md",
      "UserPasskeyManagement-item": "rounded-xl border border-gray-200",
      "PasskeyActionModal-modalContent": "max-w-sm",
    },
  }}
/>

TypeScript definitions

interface Passkey {
  id: string;
  name?: string;
  createdAt?: string;
  lastUsedAt?: string;
  deviceInfo?: string;
}

interface UserPasskeyManagementClasses {
  "UserPasskeyManagement-root"?: string;
  "UserPasskeyManagement-item"?: string;
  "PasskeyActionModal-modalContent"?: string;
}

// ComponentAction provides before/after hooks and a disabled flag.
// Both hooks receive the same data type T.
interface ComponentAction<Item, Context = void> {
  disabled?: boolean;
  onBefore?: (item: Item, context?: Context) => boolean;
  onAfter?: (item: Item, context?: Context) => void | boolean | Promise<boolean>;
}

interface UserPasskeyManagementProps {
  hideHeader?: boolean;
  customMessages?: Partial<UserPasskeyManagementMessages>;
  styling?: ComponentStyling<UserPasskeyManagementClasses>;
  addAction?: ComponentAction<void>;
  revokeAction?: ComponentAction<Passkey>;
  onFetch?: () => void;
}

Advanced customization

In addition to the component configuration described above, use the useUserPasskey hook when you need to build a custom passkey management interface.

import { useUserPasskey } from "@auth0/universal-components-react";

export function CustomPasskeyManagement() {
  const {
    passkeys,
    isLoading,
    isEnrolling,
    isRevoking,
    disableAdd,
    disableRevoke,
    currentPasskey,
    isRevokeModalOpen,
    setIsRevokeModalOpen,
    handleAddPasskey,
    handleRevokePasskey,
    handleConfirmRevoke,
  } = useUserPasskey({});

  if (isLoading) return <p>Loading passkeys…</p>;

  return (
    <>
      <button disabled={disableAdd || isEnrolling} onClick={handleAddPasskey}>
        Add passkey
      </button>

      <ul>
        {passkeys.map((passkey) => (
          <li key={passkey.id}>
            {passkey.name ?? "Unnamed passkey"}
            <button
              disabled={disableRevoke || isRevoking}
              onClick={() => handleRevokePasskey(passkey)}
            >
              Remove
            </button>
          </li>
        ))}
      </ul>

      {isRevokeModalOpen && currentPasskey && (
        <div role="dialog" aria-modal="true">
          <p>Remove {currentPasskey.name ?? "passkey"}?</p>
          <button disabled={isRevoking} onClick={handleConfirmRevoke}>
            Confirm removal
          </button>
          <button onClick={() => setIsRevokeModalOpen(false)}>Cancel</button>
        </div>
      )}
    </>
  );
}

The hook accepts customMessages, addAction, revokeAction, and onFetch. It returns passkey data, loading and action state, the active revocation target, and handlers for passkey enrollment and revocation. Use UserPasskeyManagement when you want the built-in interface. If you use the hook, implement the matching revocation confirmation UI and its dismissal behavior.

Learn more

User MFA Management

Manage MFA factors (TOTP, SMS, email OTP, push, recovery codes) alongside passkeys.

Build a Self-Service Account Security Interface

Overview, prerequisites, and framework setup for all My Account components.

Web Components

iOS Components

Android Components

User Passkey Management

Prerequisites

Configure your application

Install the component

Get started

Install the component

Get started

Install the component

Get started

Props

Display props

Action props

Customize props

TypeScript definitions

Advanced customization

Learn more

User MFA Management

Build a Self-Service Account Security Interface

​Prerequisites

​Configure your application

​Install the component

​Get started

​Install the component

​Get started

​Install the component

​Get started

​Props

​Display props

​Action props

​Customize props

​TypeScript definitions

​Advanced customization

​Learn more

User MFA Management

Build a Self-Service Account Security Interface

Prerequisites

Configure your application

Install the component

Get started

Install the component

Get started

Install the component

Get started

Props

Display props

Action props

Customize props

TypeScript definitions

Advanced customization

Learn more