Keep passkeys consistent with credentials on your server with the Signal API

Eiji Kitamura

Published: November 12, 2024, Last updated: November 29, 2024

The WebAuthn Signal API lets relying parties signal existing credentials to connected passkey providers. This lets a supporting passkey provider update or remove incorrect or revoked passkeys from its storage so users are no longer offered them.

Compatibility

Chrome supports Signal API on all desktop platforms and Android.

Safari is supportive but not yet implemented. Firefox hasn't yet shared its opinion.

Google Password Manager can update passkeys to reflect the signal. Chrome extension-based passkey providers on desktop decide whether to reflect the signal.

Background

When a passkey (a discoverable credential) is created, metadata such as a username and a display name are saved to the passkey provider (such as a password manager) along with the private key, while the public key credential is saved to the relying party's (RP's) server. Saving the username and display name helps users identify which offered passkeys to use for sign-in when prompted. This is especially useful when users have more than two passkeys from different passkey providers.

However, there are a few cases where inconsistencies between the passkey provider's passkey list and the server's credentials list can cause confusion.

The first case is when a user deletes a credential on the server. This leaves the passkey in the passkey provider untouched. The next time the user tries to sign in with a passkey, the passkey provider still presents that passkey to the user. However, the attempt to sign in will fail because the server cannot verify the public key that was deleted.

The second case is when a user updates their username or display name on the server. The next time the user tries to sign in, the passkey in the passkey provider continues to display the old username and display name even though it's updated on the server. Ideally, these are synchronized.

Signal API

The Signal API is a WebAuthn API that resolves these inconsistencies by letting RPs signal changes to the passkey provider. There are three methods:

Signal that a credential does not exist

const credential = await navigator.credentials.get({ ... });
const payload = credential.toJSON();

const result = await fetch('/login', { ... });

// Detect authentication failure due to lack of the credential
if (result.status === 404) {
  // Feature detection
  if (PublicKeyCredential.signalUnknownCredential) {
    await PublicKeyCredential.signalUnknownCredential({
      rpId: "example.com",
      credentialId: