Programmatically updating a passkey on a user's local device

TL;DR

You can update a passkey username or display name on a local device by calling updatePasskey in your frontend code. This is useful when a user changes their account identifier.

Becomes…

Note

Changing a passkey username or display name has no impact on the user’s account identifier; it’s purely for display purposes. You will identify the user based on their userId or authenticatorId, which remain unchanged.

Updating names on the device

Use the updatePasskey function in your frontend code to perform local (device) updates:

Default

import { updatePasskey, isUpdateError } from "@passlock/client";

try {
  // this will update the names in the user's password manager
  await updatePasskey({
    tenancyId,
    passkeyId,
    username: "newUsername@example.com",
    displayName: "My new username"
  });

  alert("Passkey updated");
} catch (e) {
  if (isUpdateError(e)) {
    alert("Unable to update your passkey");
  }
}

Safe

import { updatePasskey } from "@passlock/client/safe";

// this will update the names in the user's password manager
const result = await updatePasskey({
  tenancyId,
  passkeyId,
  username: "newUsername@example.com",
  displayName: "My new username"
});

if (result.success) {
  alert("Passkey updated");
} else {
  alert(result.error.message);
}

Note

Local (device) passkey updates rely on WebAuthn signals, a relatively new extension to the Web Authentication API. Not all browsers support signals, which is why you should test for support, falling back to informing the user what they should do if you can’t perform the operation programmatically.

Tip

If you have already updated multiple passkeys for a user in your backend, pair @passlock/server’s updatePasskeyUsernames helper with @passlock/client’s updatePasskeyUsernames helper. The server returns a credentials array that can be forwarded to the browser and replayed locally without repeated passkey lookups.