# Passkeys

> Passkey sign-in with Better Auth's passkey plugin: turning it on, the user's passkeys, how it works with two-factor authentication, limits and testing.

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/passkeys*

---

A passkey signs a user in with their device: a fingerprint, their face or the device PIN, with no password or email to type. The browser saves it on the device or in a password manager (iCloud Keychain, Google Password Manager, 1Password…). Passkeys work only on your site's domain, so a phishing site can't use them.

## Turn It On

```bash {% title="apps/web/.env" %}
AUTH_PASSKEY=true
```

Deployed: `pnpm --filter web exec void secret put AUTH_PASSKEY`. No migration is needed: the `passkey` table is always in the schema, so the flag only registers Better Auth's [passkey plugin](https://www.better-auth.com/docs/plugins/passkey). With it off, its endpoints don't exist and the sign-in page shows no passkey button. `/settings/security` is always open (the active sessions list); the passkeys card shows only with the flag on.

Passkeys belong to the domain of `SITE_URL` (the plugin's `rpID`), and only requests from that origin are accepted. Changing the domain makes existing passkeys stop working: users sign in another way and add a new one. Browsers show `PRODUCT_NAME` when saving a passkey.

## What Users See

- **Adding one** (`/settings/security`, Settings → Security in the account menu): **Add a passkey**, then the browser asks to save it. The list shows each passkey with the date it was added, named after the password manager when the browser tells us which one (often it doesn't, so it shows "Passkey"). **Delete** removes one.
- **Signing in:** **Sign in with a passkey** on `/auth/sign-in`. The browser offers the passkeys saved for the site, then the user continues to `next`.

A passkey is added to an account that already exists, so users always have another way to sign in. Sign-up with only a passkey isn't offered.

Adding a passkey needs a sign-in from the last 10 minutes (`FRESH_SESSION_MINUTES`), both when it starts and when the browser hands the passkey back. An older session gets "sign in again", as for two-factor changes. Deleting one needs a recent sign-in too.

## Two Factors in One

A passkey is two factors: the device that holds it, and the PIN or biometrics that unlock it. So a passkey sign-in skips the two-factor code, also for users with 2FA on.

That holds only if the device checks the user. The kit (`packages/better-auth/src/passkey.ts`) sets `userVerification: 'required'`, so Better Auth refuses a passkey without it when it is saved (`FAILED_TO_VERIFY_REGISTRATION`) and on every sign-in (`AUTHENTICATION_FAILED`). The kit's own check (`PASSKEY_USER_NOT_VERIFIED`) stays as a backstop. A security key with no PIN set can't be used until it gets one. At sign-in Better Auth only asks the browser to "prefer" verification; the server is what refuses a passkey without it.

A passkey ID already saved, for any account, is refused too (`ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED`). Better Auth only checks the user's own passkeys, and sign-in looks a passkey up by its ID alone.

The recent sign-in rule protects the same thing: without it, someone with a stolen session could add a passkey of their own and sign in later without the 2FA code.

## Limits

| Endpoint | Limit per IP |
|---|---|
| `/api/auth/passkey/generate-authenticate-options` | 10 a minute (each stores a challenge, signed out) |
| `/api/auth/passkey/verify-authentication` | 10 a minute |

A sign-in challenge lasts 5 minutes (Better Auth's default).

## Errors

The codes map to messages in `auth.errors` (`packages/i18n/src/messages/en/auth.json`):
- `PASSKEY_NOT_FOUND`: the passkey was deleted, or belongs to another site's account.
- `PASSKEY_USER_NOT_VERIFIED`.
- `CHALLENGE_NOT_FOUND`: it took too long.
- `AUTHENTICATION_FAILED`.
- `FAILED_TO_VERIFY_REGISTRATION`.
- `ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED`: this device already has a passkey for the account.
- `SESSION_NOT_FRESH`.
- `AUTH_CANCELLED`, `ERROR_CEREMONY_ABORTED` and `ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY`: the user closed the browser's prompt or it timed out.

## Testing

`packages/better-auth/src/__tests__/passkey.test.ts` runs a software authenticator (ES256, written in the test). It covers:
- adding a passkey and signing in with it;
- a 2FA user signing in without the code;
- refusing a passkey without user verification, when saving it and when signing in;
- the recent sign-in rule, at both steps of adding one and on deleting one;
- refusing a passkey ID another account already saved;
- another user's passkey can't be deleted;
- no passkey endpoints with the flag off.

E2E (`apps/e2e/tests/auth/passkey.spec.ts`) uses Chromium's virtual authenticator (`PasskeyPageObject.useVirtualAuthenticator()`). It adds a passkey on `/settings/security` and signs in with it, does the same for a user with 2FA on, and deletes a passkey and checks it no longer signs in.
