Skip to main content
Passkeys use the WebAuthn standard (FIDO2) to authenticate users with device biometrics (Touch ID, Face ID, Windows Hello) or hardware security keys. No password is ever created or stored.

Setup

1

Install

2

Add the plugin

lib/theauth.ts
origin is required and is compared exactly against the origin in the browser’s clientDataJSON. Pass an array to allow several origins. Passkey registration and the credential endpoints need an authenticated user, resolved from auth.adapter or an auth.session token. The sign-in verify endpoint issues a session only when auth.session is configured.You can also pass the same options as a top-level passkey key to createTheAuth, which exposes theauth.passkey (getRegistrationOptions, verifyRegistration, getAuthenticationOptions, verifyAuthentication, listCredentials, removeCredential, handleRequest). It is null when the key is absent.
rpId must be a registrable domain suffix of the origin. For https://app.example.com, valid values are app.example.com or example.com. Localhost works during development (set origin to the exact dev origin, for example http://localhost:3000).

Registration ceremony

A passkey is tied to a specific device. Users register once per device they want to use.
1

Get registration options

POST /auth/passkey/register/optionsReturns a WebAuthn challenge from the server. Requires an authenticated user (the user must already be signed in to register a passkey). No request body is needed.
2

Create the credential

Pass the options to the browser’s WebAuthn API:
3

Verify and store

POST /auth/passkey/register/verify
The body wraps the browser’s credential in a response field. On success, the credential is stored and the passkey is active, and the response is { credential } with the stored record.

Authentication ceremony

1

Get authentication options

POST /auth/passkey/authenticate/optionsDoes not require a session, this is the start of sign-in.
The optional userId limits allowCredentials to that user’s passkeys. Omitting it returns options with no credential restriction, so the authenticator offers any discoverable passkey for the relying party (useful for conditional UI). The body takes a user ID, not an email.
2

Get the assertion

3

Verify and start session

POST /auth/passkey/authenticate/verify
With auth.session configured, the response is { user: { id }, session: { token, expiresAt }, credential } and a theauth_session cookie is set (marked Secure when baseUrl starts with https://). Without a session manager the response is the raw { userId, credential } and no session is created. A failed assertion returns 401.

Managing credentials

Users can register multiple passkeys across different devices.

List credentials

GET /auth/passkey/credentials

Delete a credential

DELETE /auth/passkey/credentials/:id
Returns { removed: true }. Only the authenticated user’s own credentials can be removed. Use the id field of the listed credential.
If a user deletes their last passkey and has no other sign-in method, they will be locked out. Check the credential count before allowing deletion, or make sure they have another sign-in method first.

Endpoints

Options

Browser client

createPasskeyClient in @glinr/theauth-client runs the whole ceremony against the plugin’s routes, so you do not hand-roll navigator.credentials or the base64url conversions.
Results are { ok: true, data } or { ok: false, reason, message }, where reason is cancelled (the user dismissed the prompt), unsupported or failed.

Autofill (conditional UI)

With conditional: true the browser lists saved passkeys in the username field’s suggestions, and the promise resolves only if the user picks one. Give the field autocomplete="username webauthn" and abort the request when the page goes away:

Drop-in UI

The SignIn component from @glinr/theauth-ui does this for you:
It adds a “Sign in with a passkey” button and, when the browser supports it, offers saved passkeys in the email field. Set passkeyAutofill={false} for the button only.

Username and password

Password-based auth that passkeys can supplement or replace.

Magic link

Another passwordless option using single-use email links.

Sign In with Ethereum

Wallet-based auth as an alternative to device biometrics.

Authentication overview

All sign-in methods available in theAuth.
Last modified on October 13, 2026