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.
The passkey domain
Section titled “The passkey domain”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.
localhostis accepted in a development environment only.- The environment’s own login address may be used. The platform’s own domain may not.
nullremoves it, but not while thepasskeylogin 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.
Turning passkeys on
Section titled “Turning passkeys on”With the domain set, switch Passkeys on in Login methods, or add passkey to the environment’s methods:
PUT /v1/environments/{environment_id}/login-methodsContent-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.
Adding a passkey
Section titled “Adding a passkey”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
aal2if 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.
Logging in
Section titled “Logging in”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"].
Where a passkey works
Section titled “Where a passkey works”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
localhostcovers 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
localhostin 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.