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 vault. 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 returns an OrphanedPasskeyError.

Remove the orphaned passkey from the user’s device

Offer a clearly labelled action such as Remove passkey and pass the error directly to deleteOrphanedPasskey after narrowing it:

frontend/authenticate.ts

import {
  Passlock,
  isOrphanedPasskeyError,
} from "@passlock/browser";

const passlock = new Passlock({ tenancyId });

const authentication = await passlock.authenticatePasskey({
  authenticationToken,
});

if (
  authentication.failure &&
  isOrphanedPasskeyError(authentication.error)
) {
  const deletion = await passlock.deleteOrphanedPasskey(
    authentication.error
  );

  if (deletion.failure || deletion.value.warnings.length > 0) {
    showManualPasskeyRemovalInstructions();
  } else {
    showMessage("Your browser accepted the passkey removal request.");
  }
}

The helper signals only the credential represented by that authentication error. It does not contact Passlock and does not require a prepared deletion token because the vault record is already missing. Pass the live error object directly; serialized or reconstructed errors are not supported.

Browser signalling is best-effort. A successful result does not prove that every browser or password manager removed the credential. If cleanup returns an error or any warning, retain manual password-manager instructions so the user can avoid encountering the stale passkey again.