Setup
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.Registration ceremony
A passkey is tied to a specific device. Users register once per device they want to use.1
Authentication ceremony
1
Get authentication options
POST /auth/passkey/authenticate/optionsDoes not require a session, this is the start of sign-in.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.3
Verify and start session
POST /auth/passkey/authenticate/verifyauth.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
{ removed: true }. Only the authenticated user’s own credentials can be removed. Use the id field of the listed credential.
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.
{ ok: true, data } or { ok: false, reason, message }, where reason is cancelled (the user dismissed the prompt), unsupported or failed.
Autofill (conditional UI)
Withconditional: 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
TheSignIn component from @glinr/theauth-ui does this for you:
passkeyAutofill={false} for the button only.
Related
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.