WebAuthn Signal API: Update & Delete Passkeys on Client-Side

The passkey ecosystem is evolving. To facilitate change the underlying WebAuthn standard evolves fast. New features start often with a technical explainer in GitHub and then evolve into a pull request into the standard when they have been discussed sufficiently. Recently, this pull request was added into the standard draft as the WebAuthn Signal API. In this article, we will cover:

• Why is the WebAuthn Signal API needed: Which use cases does the WebAuthn Signal API support?
• How does the WebAuthn Signal API work: How exactly does the WebAuthn Signal API work? What are the recommendations for relying parties?

At time of updating this blog post on January 2025, the WebAuthn Signal API is enabled by default since Chrome 132 and was formerly known as the Reporting API before being renamed to avoid conflicts with another API of the same name.

The WebAuthn Signal API addresses specific use cases related to the management of passkeys on the client-side. Specifically, it helps keeping information in sync between the relying party (RP) and the authenticators which are part of the client-side operating systems. The following important use cases exist:

Subscribe to our Passkeys Substack for the latest news.

Subscribe

When a passkey is created, it includes several pieces of information: user.id, user.name, and user.displayName. The passkey itself is identified via the unique Credential ID.

• user.id: is a unique identifier that represents the account to which the passkey is linked. This user.id is crucial because it is used for the actual matching of the passkey to the user's account.
• user.name and user.displayName: these are meta-data used solely for display purposes in the user interface.

The following illustration shows a typical, simple database structure that explains which information would usually be stored within which field:

It's important to understand that while user.name (often an email address) and user.displayName (a more friendly, readable name) help the user identify their account in the selection UI, the real association between a passkey and an account is maintained through the user.id and the Credential ID:

• An account can have multiple passkeys, but each passkey is uniquely identified and matched to the account using the user.id
• Every passkey itself has a unique Credential ID that is generated by the authenticator

One issue arises when the user.name, which can be an email address, changes. Currently, there is no mechanism to update this change on the client-side authenticator directly. The user.name can change for various reasons, such as when a user updates their email address. Despite this change in the account's meta-data on the server side, the old user.name will continue to appear in the credential selection UI, which can cause confusion for users.

The workaround for this issue is to create a new passkey with the updated user.name and the same user.id, and then overwrite the existing passkey. However, this approach is inconvenient for several reasons:

1. Redundancy: Each user.id can have only one passkey per relying party ID, meaning the old passkey must be replaced with a new one, which is an extra step.
2. User Experience: Users will not understand why they need to create a new passkey. That’s the reason this workaround is not in widespread use.
3. Complexity: Managing passkey creation and replacement just to update metadata is an unnecessary complexity.

Email addresses, phone numbers and other identifiers can change regularly. Without a straightforward method to update user.name and user.displayName directly on the authenticator, users may encounter a persistent issue where they see and have to select a passkey associated with their old email address. This situation undermines the seamless experience that passkeys aim to provide. The WebAuthn Signal API aims to solve this problem by allowing relying parties to report updates to the meta-data of passkeys without requiring the creation of new ones. Before we explain how to implement the Signal API we will explore the second important use case that it addresses.

Become part of our Passkeys Community for updates & support.

Join

Another crucial use case is the deletion of passkeys on the client-side authenticator. Over time, users may revoke credentials via the passkey management list or delete their accounts, and it becomes necessary to ensure that these credentials are removed from the client-side authenticator to prevent them from appearing in future credential selection UIs (Conditional UI / passkey autofill).

The need for this functionality arises in several scenarios:

1. Passkey deleted via account settings: When a credential is no longer valid, such as after a user has explicitly deleted it via account settings:

From user perspective, it is difficult to understand that a deletion in their account setting, in a dialogue like the above, does not lead to the passkey being removed on this client.

2. Account Deletion: When a user deletes their account, all associated passkeys should also be removed. 3. Security Policies: Relying parties may have security policies that require the revocation of credentials after periods of inactivity or due to detected security issues.

Without a direct method to delete passkeys on the client-side, these outdated or invalid credentials continue to clutter the selection UI, leading to confusion. Users might see and attempt to use passkeys that are no longer valid, resulting in failed authentication attempts and a poor user experience.

Implementing the WebAuthn Signal API involves several steps and considerations to ensure that the functionality is integrated correctly and securely. The Signal API allows relying parties (RPs) to update or delete passkey credentials on the client-side authenticator. This section outlines the key considerations and steps for implementation.

When implementing the WebAuthn Signal API, it is crucial to keep the following considerations in mind:

• Privacy Preserving: The WebAuthn Signal API is designed to preserve user privacy as it is one of the foundations of WebAuthn. This means that there is no feedback provided to the RP about whether the requested change was processed. The API operates silently to prevent any potential leakage of information about the state of credentials.

• Authenticator Availability: The effectiveness of the WebAuthn Signal API depends on the availability of the authenticator. This includes both physical availability (e.g., the presence of a security key) and software support ( e.g., browser and operating system compatibility). The browser can only perform actions if the authenticator is accessible and supports the necessary operations without needing biometric authentication.

• Domain Restrictions: The API ensures that only the relying party associated with a specific domain can request changes to credentials related to that domain. This is a security measure to prevent unauthorized modifications by third parties.

• Credential ID as Key: When referencing passkeys, the Credential ID is the primary key used by the WebAuthn Signal API. This ID uniquely identifies the passkey on the client-side authenticator. The API allows RPs to change meta-data associated with passkeys or signal that certain passkeys should no longer be accessed, but only through the Credential ID. In case an authenticator does not know a specific Credential ID, it will silently ignore it.

These considerations are essential for understanding the most important aspects of the WebAuthn Signal API functions correctly.

The WebAuthn Signal API provides a streamlined mechanism for relying parties (RPs) to update the metadata associated with passkeys on client-side authenticators. This is especially important for ensuring that users see accurate and up-to-date information in the credential selection UI without having to create new passkeys unnecessarily. Here's how the API allows this to happen:

Updating Metadata with signalCurrentUserDetails(options)

The signalCurrentUserDetails(options) method in the Signal API is specifically designed for updating metadata of passkeys. This method allows RPs to provide the current values for user.name and user.displayName.

Here’s how the process works (see also the WebAuthn Level 3 standard).

1. Method Structure: The signalCurrentUserDetails(options) method includes the rp.id, user.id and the updated values for user.name and user.displayName.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    name: "New user name",
    displayName: "New display name",
});

2. Updating the Local Metadata: Look for locally (on the authenticator) available credentials that match the rpId and userId. For all matching credentials, the authenticator will update the credential's name and displayName.

3. Privacy Preserving: The process is designed to be privacy-preserving. The Signal API does not provide feedback to the RP about whether the updates were successfully processed, preventing any leakage of information about the state of the credentials.

4. Consistency Across Devices: By regularly running the signalCurrentUserDetails(options) methods, RPs can ensure that the metadata for passkeys remains consistent across different devices and platforms where the user may authenticate. This approach reduces the chances of outdated or incorrect information being displayed in the credential selection UI.

In the above screenshot, you can see how Google Chrome signals such an update to the user. WebAuthn Signal API is part of Chrome 130 and can be tested with Google Password Manager on desktop if the experimental web features flag is activated.

The WebAuthn Signal API provides mechanisms for relying parties (RPs) to signal the deletion of passkeys from client-side authenticators. This is essential for ensuring that outdated or invalid credentials do not appear in the credential selection UI, thus maintaining a streamlined and secure user experience. There are two methods to delete the passkeys locally: signalUnknownCredential(options) and signalAllAcceptedCredentials)(options). The former can be used in situations where the user is not authenticated, while the latter can be used when the user is authenticated. Therefore, the latter one should be preferred for privacy reasons.

Here's how the two methods work:

1. Method Structure: The signalUnknownCredential(options) method includes the rpId (relying party ID) and the credentialId (the unique identifier of the credential to be deleted).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // credential id the user just tried, base64url
});

2. Calling the Method: RPs call this method whenever they detect that a credential should be deleted. This could be immediately following an authentication attempt with an invalid credential, during account deletion, or when a user revokes a credential through account settings.

3. Handling the Method: When the signalUnknownCredential(options) method is called, the client-side authenticator tries to find credentials that match rpId and credentialID specified credential for omission. Depending on the authenticator's capabilities, the credential is removed or an authenticator-specific procedure to hide the credential in future authentication ceremonies is employed.

1. Method Structure: The signalAllAcceptedCredentials(options) method includes the rpId (relying party ID), userId and a list of valid Credential Ids allAcceptedCredentialIds (list of unique identifiers of credentials that should be kept).

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. Calling the Method: RPs call this method whenever they detect that a credential should be deleted and signal a list of valid credentials. This method should be preferred over signalUnknownCredential(options) to delete credentials.

3. Handling the Method: When the signalAllAcceptedCredentials(options) method is called, the client-side authenticator matches the rpId and userId. The authenticator that looks up all local credentials that match rpId and userId. The result is compared to allAcceptedCredentialIds. If there are local credentials that are not in allAcceptedCredentialIds, then these credentials are removed locally (or hidden depending on the authenticator).

4. Unhide Credentials: If a credentials have been hidden only (depending on the authenticator) and are now part of allAcceptedCredentialIds, then these credentials will be present in future authentication ceremonies again.

5. Useful Tips:

   • When using signalAllAcceptedCredentials(options) it's important to note that authenticators may not always be connected at the time this method is executed. As a result, relying parties might consider running signalAllAcceptedCredentials(options) periodically, such as during every sign-in, to ensure that all credentials are up-to-date.
   • Relying parties must be cautious when specifying the list of credential IDs (allAcceptedCredentialIds). Credentials that are not included in this list may be hidden or removed by the authenticator, potentially irreversibly. To prevent valid credentials from being mistakenly omitted, it is crucial to ensure that the list is complete. If a valid credential ID is accidentally left out, it should be re-added to signalAllAcceptedCredentials(options) as soon as possible to make it visible again, assuming the authenticator supports this.
   • Whenever possible, authenticators should prefer temporarily hiding credentials instead of permanently removing them. This approach can help facilitate recovery if a valid credential ID was accidentally omitted by the relying party, allowing it to be restored without permanent loss.

In the above screenshot, you can see how Google Chrome signals deletes. WebAuthn Signal API is part of Chrome 132 and can be tested with Google Password Manager on desktop.

To effectively implement the WebAuthn Signal API and ensure seamless synchronization of passkey metadata across client-side authenticators, consider the following recommendations:

• Watch out for WebAuthn Signal API updates and actual implementation: Stay informed about the latest developments and updates related to the Signal API. The WebAuthn Signal API is enabled with Google Chrome 132, followed by other browsers (e.g. Safari announced support as well). Regularly check the progress and updates on the WebAuthn Signal API to ensure your implementation aligns with the latest standards and practices. We will update this blog post in the future, it is currently based on the information available from January 14, 2025.
• Start with the signalAllAcceptedCredentials(options) approach after every successful login: This approach ensures that all metadata and credential IDs are updated in a single method, simplifying the process and maintaining consistency across devices and platforms and at the same time deactivates deleted or stale credentials.
• Real-time messaging with signalUnknownCredential(options) for large-scale deployments: Consider using real-time messaging with the signalUnknownCredential(options) method in large-scale deployments or when there is a need for immediate updates. This method can enhance the efficiency and accuracy of credential management, ensuring that invalid or outdated credentials are promptly removed from the selection UI.

By following these recommendations, you can implement the WebAuthn Signal API effectively once it is supporting, ensuring that passkey metadata remains up-to-date and consistent across all client-side authenticators, thereby providing a smooth and secure user experience for passkeys.

The WebAuthn standard is continually evolving, becoming more feature-rich on a monthly basis. The introduction of the WebAuthn Signal API is a significant step forward in managing passkey meta-data and deletions on client-side authenticators. This API addresses the crucial use cases of keeping information in sync between relying parties (RPs) and authenticators, and ensuring that invalid or outdated passkeys are removed, thereby improving the user experience.

• Why is the Signal API needed? The Signal API is essential for updating passkey metadata and deleting passkeys on client-side authenticators. It resolves issues related to outdated user.name and user.displayName information, which can cause confusion when credentials are presented in the selection UI. Additionally, it helps in maintaining a clean and secure credential selection interface by removing revoked or deleted passkeys.
• How does the Signal API work? The Signal API works by allowing RPs to call methods about the current state of credentials, including updates to metadata and signaling the deletion of passkeys. These reports are processed by the client-side authenticator, ensuring that the information presented to users is accurate and up-to-date. The API is designed to be privacy-preserving and operates without providing feedback to the RP about the success of the updates.

As the WebAuthn standard evolves, it benefits from the diverse interests of its participants, who push different parts of the standard forward. Keeping an eye on these developments is crucial for staying up-to-date with the latest enhancements and ensuring that implementations remain aligned with the latest best practices and standards. The WebAuthn community continues to drive innovation, making authentication more secure and user-friendly.