Pre-selecting a specific passkey (allowCredentials)

TL;DR

If you know which passkeys are associated with an account, you can pre-select them via the allowCredentials property. The client device will then limit passkey selection to one of those.

If the user is already logged into their account, or they have presented a username/email in a two-step login flow, you can help them out by preselecting the passkey they should use to authenticate.

frontend/login.ts

import { authenticatePasskey } from "@passlock/client";

// from your backend
const allowCredentials = [existingPasskeyId]
const result = await authenticatePasskey({ allowCredentials, ... })

Given that you already know their user ID (or claimed ID), you can look up the passkeys associated with the account and pass them to authenticatePasskey via the allowCredentials property.

Tip

This is especially valuable during re-authentication operations e.g. security critical steps.

Imagine a user is signed into your system using their personal account. They want to change their email and you ask them to re-authenticate with their passkey. If they also have a work account, they might select this passkey and you’d error out.

By pre-selecting the personal passkey you can ensure that this is the only passkey the browser will offer them.

This is conceptually similar to the excludeCredentials registration option.

Handle missing passkeys

You can end up with a scenario in which a user has deleted a passkey locally but it’s still linked in your backend system. When you pass the missing passkey id via allowCredentials the local device will return an error indicating that no passkey with the given id can be found locally:

frontend/login.ts

import { authenticatePasskey, isPasskeyNotFound } from "@passlock/client";

const result = await authenticatePasskey({ ... });

if (isPasskeyNotFound(result)) {
  // fall back to another method e.g. one-time code
  // or username/password + TOTP authentication
}