Handling missing/orphaned passkeys

A passkey could be deleted from your vault, but remain on the user’s device.

Equally, the user might remove it from their device, but you still retain a record in your backend.

You must account for both scenarios.

Missing device passkey

When using the allowCredentials property, you’re telling the device to use a specific passkey which might not exist on the device. In this case the device will usually prompt the user to adopt the roaming authenticator flow.

Assuming the user does not have the passkey(s) on another device they will cancel the operation. You should test for the generic OtherPasskeyError and ask them to authenticate via a different mechanism.

Missing vault passkey (orphaned passkey)

Conversely, if you allow the user to use any passkey on their device (discoverable: true), the device could present a passkey that was deleted from your vault.

In this case authenticatePasskey will return an OrphanedPasskeyError. It’s important to inform the user that they should remove this passkey, otherwise they’ll keep running into the same issue.

For passkeys that still have a known vault record, use the prepared passkey removal flow so the browser receives only a short-lived deletion token. For true orphaned passkeys with no matching vault record, tell the user how to remove the passkey manually from their password manager.