Skip to content
NuxtBase logo NuxtBase Docs

Passkeys

NuxtBase includes passkey support through @better-auth/passkey.

In the shipped product, passkeys appear in two places:

  • passkey sign-in on /login
  • passkey management in dashboard security settings

Login Experience

Section titled “Login Experience”

The login page includes a dedicated Sign in with Passkey button.

This means passkeys are a real primary auth method in the UI, not only an account-settings enhancement.

If the browser and authenticator succeed, the user is redirected into the app using the same post-login rules as other sign-in methods.

Managing Passkeys

Section titled “Managing Passkeys”

Users manage passkeys from the security settings screen.

The shipped management UI supports:

  • listing passkeys
  • adding a passkey
  • renaming a passkey
  • deleting a passkey

That makes passkeys maintainable for real users, which is especially important once people start registering more than one device.

Registration Options

Section titled “Registration Options”

When adding a passkey, the user can choose the authenticator attachment type:

  • platform
  • cross-platform

In practical terms, this maps to the two common passkey styles:

  • device-bound platform authenticators
  • cross-device or hardware-key style authenticators

The form also accepts an optional display name so the saved passkey is easier to identify later.

Defaults and Fallbacks

Section titled “Defaults and Fallbacks”

Passkey runtime setup is derived from:

  • BETTER_AUTH_PASSKEY_RP_ID
  • BETTER_AUTH_PASSKEY_RP_NAME

If these are not set explicitly, the template falls back to:

  • hostname from the auth or site URL for RP ID
  • app name for RP name

That setup guidance lives in setup/authentication-setup, but it matters here because an incorrect RP ID usually shows up as “passkeys do not work” in the product.

What To Test

Section titled “What To Test”
  1. sign in with email/password first
  2. open dashboard settings
  3. add a passkey with the default platform option
  4. sign out
  5. use Sign in with Passkey on the login page
  6. return to settings and confirm the passkey can be renamed or deleted

Practical Advice

Section titled “Practical Advice”

Start with one platform passkey on a single browser and machine. Once that works, test cross-platform or hardware-key style authenticators if your product needs them.