Passkeys

Passkeys

Sign in with a fingerprint, face, PIN, or hardware security key instead of typing a password.

Where to find it

Open Settings and select the Account tab. The Passkeys section sits below the two-factor authentication block.

Admin: Passkey login is off by default. Turn on Enable passkey login in Admin → Settings, under the Passkey login card.

The section is hidden entirely when the feature is off and you have no passkeys enrolled. If you already have passkeys, the list stays visible even after an admin turns the feature off, so you can always clean them up.

Enrolling a passkey

1. Click Add a passkey.
2. Enter your current password — TREK asks for it so a hijacked session cannot silently plant a passkey.
3. Optionally give the passkey a name (the placeholder suggests something like iPhone). Leave it blank and TREK names it Passkey (synced) or Passkey depending on the authenticator.
4. Click Add a passkey again and follow your device prompt (Touch ID, Windows Hello, Android screen lock, a YubiKey, and so on).

Every passkey is registered with user verification required, so a biometric or PIN check always happens — a bare "tap the key" gesture is not enough. The same authenticator cannot be enrolled twice on one account, and enrolment expires if you take longer than five minutes.

If you dismiss the browser dialog you get Passkey setup cancelled and nothing is stored.

Signing in with a passkey

On the login page, a Sign in with a passkey button appears below the password form (separated by an or divider). Click it, pick your passkey in the browser prompt, and you are signed straight in — no username, no password, no second step.

The button only shows when all of these hold:

• An admin enabled passkey login.
• A usable WebAuthn domain resolves for the deployment (see Setup requirements).
• The instance is not in OIDC-only mode.
• You are on the sign-in form (not registration, the 2FA step, or a forced password change).

TREK never reveals which accounts have passkeys: the login ceremony uses discoverable credentials, every failure returns the same generic Authentication failed, and responses are padded to a fixed minimum latency so timing gives nothing away.

Managing your passkeys

Each entry in the list shows its name, a Synced or This device badge, the date it was Added, and either Last used with a date or Never used.

• Rename (pencil icon) — edit the name inline; press Enter to save, Escape to cancel. Names are capped at 60 characters.
• Delete (trash icon) — confirms with Remove this passkey? Confirm with your password. and requires your current password.

Removing every passkey can never lock you out — your password always remains as a fallback.

Admin: In Admin → Users, editing a user exposes a Reset passkeys action that removes all of that user's passkeys at once (for a lost device). The user can still sign in with their password.

Passkeys and two-factor authentication

A user-verified passkey is already two factors — possession of the device plus a biometric or PIN — so it mints a session directly and does not prompt for a TOTP code afterwards.

The same reasoning applies to the admin Require two-factor authentication (2FA) policy: owning at least one passkey satisfies that policy exactly like an enabled TOTP authenticator does. A brand-new user under the policy can enrol a passkey instead of setting up an authenticator app; the enrolment endpoints stay reachable while the rest of the API is blocked, so nobody gets stuck. See Two-Factor-Authentication.

Setup requirements

Passkeys are bound to a domain (the Relying Party ID). If no usable domain resolves, the feature stays hidden even with the toggle on, and the admin card shows a warning.

Admin: The Passkey login card also has Relying Party ID (domain) and Allowed origins fields. Leave them empty to derive both from APP_URL. Changing the RP ID later invalidates existing passkeys.

Both values can be pinned with environment variables, which take priority over the Admin panel fields:

• WEBAUTHN_RP_ID — the registrable domain, e.g. trek.example.com. Bare IP addresses are rejected.
• WEBAUTHN_ORIGINS — comma-separated allowed origins, e.g. https://trek.example.com.

See Environment-Variables for the full description of both.

Audit and rate limits

Enrolment, deletion, and passkey logins are recorded in the Audit-Log (user.passkey_register, user.passkey_delete, and user.login with method: passkey). If an authenticator ever replays a stale signature counter, TREK rejects that attempt and logs user.passkey_clone_suspected without disabling the credential.

Login and enrolment attempts are rate limited per IP over a 15-minute window.

Permissions

No TREK permission gates passkeys — any signed-in user can enrol and manage their own. Only the instance-wide toggle and the WebAuthn domain configuration are admin-controlled, and the Reset passkeys action is admin-only.

See also

• Login-and-Registration
• Two-Factor-Authentication
• User-Settings
• Environment-Variables
• Security-Hardening
• Audit-Log