Skip to main content

​
Keeping the Authenticator and Your Server in Sync

Your server and the user’s credential manager hold two separate lists of passkeys, and nothing keeps them aligned automatically. When they drift, the user pays for it: a passkey your server no longer accepts is still offered in the account chooser, the user selects it, authenticates with Face ID or a fingerprint, and then the login fails. That is the worst failure shape in passkey UX, because everything felt successful right up to the moment it did not. The entry also persists, so the same failure repeats on every attempt until the user digs into their credential manager settings. Signalling closes that gap. It is not a UI flow, but it decides whether several of the flows in this section succeed, and it belongs in every production integration. On the web the stale credential surfaces through Conditional UI, which offers whatever the credential manager holds regardless of what your server still accepts.
Support (August 2026): Chrome and Edge 132+ on desktop, Chrome 144+ on Android, Safari 26 (iOS 26, macOS 26). Firefox has no implementation, and the API is not available in Android WebView — which is one more reason to prefer native Credential Manager over an embedded webview. For native apps see the native Signal API.

​
The three signals

1

On a failed login: signal the unknown credential

  • When an assertion arrives for a credential your server does not recognise, call signalUnknownCredential({ rpId, credentialId }).
  • This carries no user identifier and no credential list, so it is safe to call when the user is not authenticated.
  • Google Password Manager hides rather than deletes the passkey, so it can be restored if the signal was sent in error.
2

On a successful login: reconcile the full list

  • Call signalAllAcceptedCredentials({ rpId, userId, allAcceptedCredentialIds }) with every credential ID your server currently accepts for that user.
  • The provider may hide or remove passkeys missing from the list. If it supports restoration, credentials included again in a later complete list may be unhidden.
3

After the user deletes a passkey in settings

  • Call signalAllAcceptedCredentials again from your passkey management screen so the provider can hide or remove the credential immediately, rather than waiting until the user’s next login to receive the updated list.
4

After a profile change

  • Call signalCurrentUserDetails({ rpId, userId, name, displayName }) so the account chooser shows current information.
  • Note that if the user has manually edited the name in Google Password Manager, their edit wins and your signal will not override it.
Use the right signal for a failed login. On a failed login call signalUnknownCredential, never signalAllAcceptedCredentials. The latter requires a user ID and the complete valid list, neither of which you can assemble safely for an unauthenticated caller, and it reveals how many passkeys an account has.
Never send a partial or accidentally empty credential list. The reconcile signal may hide or remove every passkey it does not find in the accepted list. An empty list is valid only when the authoritative server state confirms that the authenticated user has no accepted credentials, for example after deleting their final passkey. Treat the code that assembles this list as high-risk, and test it against accounts with zero, one and several credentials.

​
Why Server-Side Revocation Still Needs Client Cleanup

Deleting the public key on your server revokes the credential immediately: any later assertion from it must be rejected. What that server-side action cannot do is remove the stale entry from the user’s locally installed credential manager, because your backend has no direct channel to the user’s password manager. Client-side cleanup can happen only when the user’s client runs again. Signal an unknown credential after a failed assertion, and reconcile the complete accepted list during the next authenticated session. Running that reconciliation after every successful sign-in is how server-initiated changes eventually reach credential managers that were not available when the revocation happened.
Signals resolve with no information about what the provider did. You never learn whether a credential existed or whether the provider acted, which is deliberate and privacy-preserving. It also means signalling can never serve as an audit trail or a source of truth. Treat it as fire-and-forget hygiene, and never block a UI flow on the result.
On the web the reconcile call is signalAllAcceptedCredentials, and the list it hides against is allAcceptedCredentialIds.

​
Error handling

Both failure modes are rejections on a DOMException:
  • SecurityError — the relying party domain is not valid
  • TypeError — a credentialId, userId or list entry is not valid base64url
Branch on error.name only. Message strings are not part of the contract.

​
Further reading