Passkey Authentication

Passkeys provide a phishing-resistant, passwordless authentication method based on the WebAuthn standard. Users can register a passkey tied to their device (biometrics, hardware security key, or platform authenticator) and use it to sign in without a password.

Requirements

Browser and Device Support

Passkeys require WebAuthn support in the user's browser and operating system. The login interface automatically detects support and only displays the passkey option when it is available.

Supported environments include:

  • Chrome 67+ on Windows, macOS, Android
  • Safari 14+ on macOS, iOS/iPadOS
  • Firefox 60+ on Windows, macOS, Linux
  • Edge 18+ on Windows

Authenticator types that work with passkeys:

  • Platform authenticators: Windows Hello, Touch ID, Face ID, Android biometrics
  • Roaming authenticators: FIDO2 hardware security keys (e.g. YubiKey)

Signing In with a Passkey

  1. Navigate to the login page.
  2. If your browser supports WebAuthn, a Sign in with Passkey button appears alongside the standard credential and social login options.
  3. Click the button. Your browser or operating system will prompt you to authenticate using a saved passkey (biometric scan, PIN, or security key).
  4. On success, you are signed in and the page reloads.

If no passkey has been registered yet, the browser may show a "no credentials found" message. Register a passkey first through the user profile (see below).

Registering a Passkey

Passkeys are managed from the Auth Methods section of your user profile.

  1. Open your profile (click your avatar or name in the top navigation).
  2. Scroll to the Auth Methods section.
  3. Optionally enter a name for the passkey (e.g. "Work laptop", "iPhone").
  4. Click Add Passkey.
  5. Your browser will prompt you to create a credential using your device authenticator.
  6. After confirmation, the new passkey appears in the list.

You can register multiple passkeys for the same account — one per device is recommended.

Deleting a Passkey

  1. Open your profile and navigate to the Auth Methods section.
  2. Locate the passkey you want to remove.
  3. Click the Delete (or trash icon) button next to it.
  4. The passkey is immediately revoked and removed from the list.

Note: Deleting a passkey from your profile does not automatically remove it from your device's credential store. Use your operating system's passkey manager to remove it there as well.

Linking and Unlinking Social Accounts

The Auth Methods section also shows all social providers (GitHub, Microsoft, etc.) linked to your account. You can:

  • Link an additional provider by clicking the link button next to an unlinked provider.
  • Unlink a provider by clicking the unlink button next to a linked provider.

At least one active authentication method must remain on your account; unlinking is blocked if it would leave you with no way to sign in.

Server Configuration

Passkey support is enabled by default via the @better-auth/passkey plugin included in the shared Better Auth configuration:

import { passkey } from "@better-auth/passkey";

// Automatically included in createBetterAuthSharedConfig()
plugins: [passkey()]

No additional server-side configuration is required for basic passkey functionality. The following API endpoints are registered automatically:

Endpoint Method Description
/api/auth/passkey/generate-register-options GET Returns WebAuthn registration options
/api/auth/passkey/verify-registration POST Verifies and stores the new credential
/api/auth/passkey/generate-authenticate-options GET Returns WebAuthn authentication options
/api/auth/passkey/verify-authentication POST Verifies authentication and issues a session
/api/auth/passkey/list-user-passkeys GET Lists passkeys for the authenticated user
/api/auth/passkey/delete-passkey POST Deletes a passkey by ID
Markdown | llm.txt