Skip to content

Passkeys

A passkey is a key pair kept by the user’s device or password manager and unlocked with a fingerprint, a face or a PIN. In SeekAuth a passkey is both a way in and a second factor: a passkey login is a two-step login (aal2) by itself, and a user with a passkey can use it after an email code or a password.

A passkey belongs to a domain, and browsers use it only on pages of that domain. Before passkeys can be turned on, the environment needs its passkey domain (passkey_rp_id): normally your app’s own domain, such as your-app.com, so that the passkey works on every page under it.

Set it on the Login methods page, or with the management API (admin role):

PATCH /v1/environments/{environment_id}
Content-Type: application/json
{ "passkey_rp_id": "your-app.com" }
  • It is a domain name of at least two labels, saved in lower case without a trailing dot. An IP address is not accepted.
  • localhost is accepted in a development environment only.
  • The environment’s own login address may be used. The platform’s own domain may not.
  • null removes it, but not while the passkey login method is on (409).

Changing the passkey domain later leaves the passkeys made for the old one unusable: choose the domain your app will keep.

With the domain set, switch Passkeys on in Login methods, or add passkey to the environment’s methods:

PUT /v1/environments/{environment_id}/login-methods
Content-Type: application/json
{ "methods": ["email_code", "passkey"] }

Turning passkey on without a passkey domain is refused (400). As a second factor, a passkey works whenever the environment has a domain, even with the login method off.

Users add passkeys in your app’s settings page, never during a login. Put auth-react’s <Passkeys /> there:

import { Passkeys } from '@seek-services/auth-react'
export function SecuritySettings() {
return <Passkeys />
}
  • A user can have up to 10 passkeys.
  • Adding or removing one needs a login from the last ten minutes (at aal2 if the user already has a second factor); the component asks for it. Renaming does not.
  • A first passkey that is also the user’s first second factor comes with 10 recovery codes, shown once.
  • The user is emailed when a passkey is added or removed.

Without React, use auth.passkeys.add() of auth-js, or the account API directly.

The login UI offers a passkey in three places, when the passkey method is on:

  • a Sign in with a passkey button;
  • the browser’s autofill of the email field, which lists the user’s passkeys while they type;
  • the second step, for a user who has a passkey.

A passkey login is aal2 with amr ["passkey"]. Used after an email code, it gives ["email", "passkey"].

Two rules decide where the login UI shows anything about passkeys:

  • The browser’s rule. The page’s host must be the passkey domain or a name under it. A one-label domain such as localhost covers that host only.
  • SeekAuth’s rule. The page must be one SeekAuth knows: the environment’s login address, an allowed origin of one of its clients, or localhost in development, on the passkey domain or under it. At a login it must also be the page the login runs on: the page that started the embedded login, or the hosted login page. A passkey answer made on another page of the environment does not count. A native app at the embedded login sends no page of its own; its platform passkey names the web origin the app is associated with (on iOS, https:// and the passkey domain), which counts when it is an allowed origin of that native app’s own client.

Where either fails, or the browser has no WebAuthn, the login UI says nothing about passkeys and <Passkeys /> explains why none can be added (usePasskeys().unavailable: unsupported, not_configured, wrong_domain or limit).

Passkeys are made with user verification required, as discoverable credentials, without attestation. SeekAuth accepts ES256, EdDSA and RS256 keys, and at every login checks that the user was present and verified, the page’s origin, the passkey domain, and that the authenticator’s signature counter never goes back.