Passkey (WebAuthn) MFA — Frontend Handover

This document explains how to integrate the frontend with the passkey MFA support added to
identity-mfa (registration/management) and identity-session (login).

Passkeys use the browser's native WebAuthn API. The backend uses
@simplewebauthn/server to generate/verify challenges, so the
frontend should use the matching client library,
@simplewebauthn/browser:

That library exposes two helpers used throughout this doc:

startRegistration(options) — wraps navigator.credentials.create()

startAuthentication(options) — wraps navigator.credentials.get()

Both take the JSON options object returned by our API as-is, and both return a JSON response
object that should be sent back to our API unmodified (as attestation_response /
assertion_response).

Requires HTTPS (or localhost) — WebAuthn will not work over plain HTTP in any other host.

1. Registering a new passkey (user is already logged in)

This is a two-step flow: request registration options, then verify what the browser returns.

Step 1 — Request registration options

POST /identity-mfas

Requires the normal authenticated session (JWT), same as any other identity-mfa creation call.

Request body:

{
  "type": "passkey",
  "device_id": "a stable, client-generated identifier for this device/browser",
  "device_name": "e.g. \"Chrome on Sam's MacBook\" (optional, shown in device lists)"
}

device_id is required for passkeys. It's how we tell one registered device/browser apart
from another for the same identity (also used later to remove a specific passkey). Generate it
once per device/browser (e.g. crypto.randomUUID()) and persist it (e.g. localStorage) — do
not regenerate it on every registration attempt from the same device.

device_name is optional but recommended for a good "manage your passkeys" UX.

Response (201):

{
  "id": "01J...",
  "identity_id": "01J...",
  "type": "passkey",
  "status": "pending",
  "contexts": ["login"],
  "system_meta": { "passkey": { "device_id": "...", "device_name": "...", "device_type": null } },
  "created": 1234567890,
  "updated": 1234567890,
  "provisioning": {
    /* PublicKeyCredentialCreationOptionsJSON — pass this directly to startRegistration() */
  },
  "backup_codes": null
}

Keep the id from the response — you'll need it in step 2 (as the :id path param).

Step 2 — Create the credential in the browser and verify it

Then confirm it with the server:

PATCH /identity-mfas/:id

{
  "attestation_response": "<the object returned by startRegistration()>"
}

Response (200) is the same normalized shape as step 1, now with status: "active".

The registration challenge expires after MFA_PASSKEY_CHALLENGE_TTL_MS (5 minutes by default) —
if the user takes too long between step 1 and step 2, this call will fail and step 1 must be
repeated.

Removing a passkey

PATCH /identity-mfas/:id

{ "status": "inactive" }

Notes:

This works directly (no re-verification step) — it's treated like "remove this device".

The API will reject this (403) if it's the identity's last active MFA method usable for
login, to avoid locking the user out. Surface this as a normal error message; there's nothing
the frontend needs to do differently, just handle the error response.

2. Logging in with a passkey

Login always starts the same way as password login, then branches into an MFA step if the
identity has any active login MFA methods.

POST /identity-sessions

{ "email": "...", "password": "..." }

If mfa_required is false, login is complete — nothing else to do.

If mfa_required is true, the response looks like:

{
  "mfa_required": true,
  "session_id": "01J...",
  "session_token": "...",
  "expires_at": 1234567890,
  "next_steps": [
    { "identity_mfa_id": "01J...", "type": "passkey" },
    { "identity_mfa_id": "01J...", "type": "email-mobile", "masked_email": "j***@example.com" }
  ]
}

next_steps tells you which MFA methods are available. If any entry has "type": "passkey",
you can offer a "Sign in with a passkey" option (in addition to, or instead of, the existing OTP
flow — there is no need to pick a specific identity_mfa_id for passkeys, since the browser
handles that as part of resolving which credential to use).

Step 2 — Request passkey authentication options

POST /session-otps

{ "session_token": "<from step 1>", "type": "passkey" }

Response (201):

{
  "type": "passkey",
  "options": {
    /* PublicKeyCredentialRequestOptionsJSON — pass this directly to startAuthentication() */
  }
}

If the identity has no active passkeys, this returns a 404.

Note: this is the same endpoint used for requesting an email OTP — pass identity_mfa_id
instead of type for that flow. The two are mutually exclusive per call.

Step 3 — Get the assertion from the browser and complete the session

PATCH /identity-sessions

{
  "session_token": "<from step 1>",
  "assertion_response": "<the object returned by startAuthentication()>"
}

The server figures out which registered passkey was used from the assertion itself — you don't
need to pass identity_mfa_id. Response (200) is the standard completed-session shape:

{
  "mfa_required": false,
  "session_token": "...",
  "session_id": "01J...",
  "identity_id": "01J...",
  "expires_at": 1234567890,
  "identity": { "name": "...", "primary_email": "...", "status": "active" }
}

This session_token replaces the pending one from step 1 — use it going forward exactly like the
token from a non-MFA login.

The authentication challenge from step 2 also expires after MFA_PASSKEY_CHALLENGE_TTL_MS (5
minutes by default); if the user takes too long, step 2 must be repeated.

Error reference

These are the new error messages the frontend may encounter (in addition to the existing
identity-mfa / identity-session errors already handled elsewhere):

Message	When
`A device_id is required to enable passkey MFA`	`device_id` missing on `POST /identity-mfas` with `type: passkey`
`This passkey registration request has expired. Please try again`	Too long between registration steps 1 and 2
`A passkey registration response is required to verify this method`	`attestation_response` missing on the verify `PATCH`
`The passkey registration response is invalid`	Browser response failed WebAuthn verification
`This passkey is already registered to an identity`	The exact same credential is already registered (e.g. re-registering)
`This is the last active login MFA method for this identity and cannot be deactivated`	Trying to remove the identity's only active login MFA method
`Either identity_mfa_id or type is required`	Neither provided on `POST /session-otps`
`No active passkeys are registered for this identity`	`POST /session-otps` with `type: passkey` but identity has none
`A passkey assertion response is required to complete this login`	`assertion_response` missing on `PATCH /identity-sessions`
`This passkey is not registered for this identity`	Assertion's credential id doesn't match any active passkey for the session's identity
`No pending passkey login challenge found for this session`	Step 3 attempted without (or after expiry of) step 2's challenge
`The passkey login response is invalid or has expired`	Browser assertion failed WebAuthn verification, or a sign-counter anomaly was detected

All of the above are returned as standard API error responses — no special-case handling is
needed beyond displaying the message and, where relevant, letting the user retry from the
appropriate step.

Summary of endpoints

Step	Method	Path	Auth
Start passkey registration	`POST`	`/identity-mfas`	JWT (logged in)
Verify passkey registration	`PATCH`	`/identity-mfas/:id`	JWT (logged in)
Remove a passkey	`PATCH`	`/identity-mfas/:id`	JWT (logged in)
Password login	`POST`	`/identity-sessions`	none
Request passkey login options	`POST`	`/session-otps`	none (uses `session_token`)
Complete passkey login	`PATCH`	`/identity-sessions`	none (uses `session_token`)

Passkeys

Passkey (WebAuthn) MFA — Frontend Handover#

1. Registering a new passkey (user is already logged in)#

Step 1 — Request registration options#

Step 2 — Create the credential in the browser and verify it#

Removing a passkey#

2. Logging in with a passkey#

Step 1 — Password login#

Step 2 — Request passkey authentication options#

Step 3 — Get the assertion from the browser and complete the session#

Error reference#

Summary of endpoints#