Supporting legacy applications with progressive passkey rollout

Note

If you haven’t already done so, please check out the authentication patterns document.

“Legacy” is a bit harsh. In this guide we’re talking about a live application with an existing user base, existing sessions, established recovery processes, support scripts, and users who currently know they sign in with a username and password.

That context matters. You cannot convert a password account into a passkey account entirely on the server. A passkey has to be created by the user’s browser, operating system, password manager, or security key, then linked to the user’s account in your backend.

For an existing application the safest strategy is usually a progressive migration: keep the existing login path working, add passkeys as an additional authenticator, and gradually make passkeys the preferred way to sign in.

Recommended default

For most existing applications, start with passkeys as an additional sign-in method, then move enrolled users toward passkey-first authentication. Treat password removal as a later account-level choice, not the first release.

Risks and pitfalls

The fallback can undermine the passkey

Passkeys are phishing-resistant, but the account is only as strong as the weakest way back in. If a user can still reset the password via a weak email flow, receive an SMS one-time code, or convince support to bypass passkey authentication, attackers will target those paths instead.

Keep fallback paths during migration, but harden them. Rate-limit password and recovery attempts, notify users about sensitive changes, review support recovery processes, and require stronger checks before allowing account takeover-sensitive actions.

Unsafe passkey registration can persist an attack

Registering a passkey is a sensitive account change. If an attacker signs in with a stolen password and immediately adds their own passkey, they may retain access even after the password is changed.

Only allow passkey registration from a trusted, recently authenticated session. For higher-risk accounts, require existing MFA, a one-time code, or step-up authentication before creating the passkey. Consider sending an email notification when a new passkey is added.

Hard enforcement can lock out real users

Some users will be on unsupported browsers, managed devices, shared machines, or platforms where their passkeys are not synced. Others will lose a device or accidentally delete a passkey from their password manager.

Do not assume a single passkey is enough. Allow users to register more than one passkey, and design a recovery route for users who cannot use their registered passkey. Your recovery route should be deliberate and audited, not an afterthought.

The relying party ID is hard to change later

Passkeys are bound to a Relying Party ID, usually your domain. If you choose the wrong RP ID during migration, credentials may not work across the domains or subdomains where users expect to sign in. You will need to resort to domain migration which adds complexity.

Decide the RP ID before broad enrollment. This is especially important if you have multiple login domains, white-label domains, native app handoff, or a planned domain migration.

Users may not understand the new path

Existing users already have a mental model: “I enter my email and password.” If the browser suddenly asks for a passkey while the page still looks like a password form, some users will cancel or assume something is wrong.

Use clear language such as “Sign in with a passkey” and present it as an alternative to the password form. Autofill can be useful, but test it with your audience; explicit two-step flows are often easier to understand during migration.

Backend and device state can drift

A user may delete a passkey from their device but leave the backend record in your system. Or they may remove the passkey from your application while the local credential remains in their password manager.

Handle both cases. Use allowCredentials when you know which passkeys belong to an account, and account for missing or orphaned passkeys in your error handling and account management screens.

Poor metrics make the rollout hard to manage

Track registration attempts, successful registrations, sign-in success rates, fallback usage, recovery events, and support contacts. Without this, you won’t know whether users are adopting passkeys successfully or quietly falling back to passwords.

Recommended migration plan

As with most migrations we recommend an “Expand, Migrate, Contract” approach:

1. Expand - Allow users to register and sign in with passkeys alongside existing mechanisms.
2. Migrate - Prompt users to create passkeys. Prompt after login, display a banner in your app, email them, use social media to get the word out.
3. Contract - Remove password based authentication for accounts with an active passkey.

1. Prepare the account model

Allow each account to have zero, one, or many passkeys. Store enough metadata to help users manage them later, for example the creation time and a friendly label. Displaying the associated platform e.g. Apple or Google is especially helpful. Users typically need one passkey for each ecosystem.

Before registering a new passkey, pass existing credential IDs via excludeCredentials so the user doesn’t create duplicate passkeys on the same synced platform account.

2. Keep username and password working at first

Do not start by removing passwords. Your first passkey release should be additive: users can continue signing in with their existing credentials while enrolled users can choose passkey authentication.

This gives you a safe rollout path, lets support teams learn the new flows, and avoids locking out users whose devices are not ready.

3. Offer passkey registration after successful legacy sign-in

The best enrollment moment is usually immediately after a successful password sign-in, especially if the user also completed MFA. They are present, authenticated, and already thinking about sign-in.

Check passkey support before prompting. If the device supports passkeys, explain that adding one will make future sign-ins faster and safer. If the device does not support passkeys, continue with the existing flow to avoid blocking the user.

4. Add passkey management to account settings

Users should be able to add, name, review, and remove passkeys from account settings. Encourage more than one passkey for users who work across devices or ecosystems, for example a personal device and a work machine.

Treat passkey removal carefully. If the user is deleting their last passkey, confirm that another recovery or sign-in method is still available.

5. Move login toward a two-step flow

For many existing applications, a two-step login flow is the cleanest migration pattern:

1. Ask for the account identifier, such as email or username.
2. Look up the account and its registered passkeys.
3. If passkeys exist, authorize passkey authentication and supply allowCredentials.
4. If no passkeys exist, continue with password authentication and offer registration after success.

This lets you offer the right authentication options for the account without asking the user to remember whether they have already registered a passkey.

Single-step login

If you keep a single username/password form, present “Sign in with a passkey” as a distinct option. You can also consider autofill, but it may be less obvious to users who are still expecting a password form.

6. Prefer passkeys for enrolled users

Once an account has a passkey, make passkey sign-in the recommended path. You can still keep password sign-in available during the transition, but the UI should guide enrolled users toward the stronger mechanism.

For sensitive operations, such as changing an email address, changing recovery settings, adding another passkey, or deleting an account, use passkeys for step-up authentication where possible.

7. Harden and reduce fallback paths

After adoption is healthy, start reducing reliance on passwords. This does not have to mean removing passwords for everyone at once.

You might:

• require MFA before password fallback for enrolled users,
• require passkey step-up before changing recovery settings,
• offer an optional passwordless mode,
• make password removal available only after the user has registered more than one passkey or has a strong recovery method.

The important principle is that fallback should become safer as passkeys become more common. Otherwise the password remains the real security boundary.

8. Make enforcement gradual and account-specific

Only consider mandatory passkeys after you have data showing successful enrollment and authentication across your user base. Even then, prefer account-specific enforcement: managed enterprise tenants, administrator accounts, or high-risk users may be ready before the entire application is.

Roll out in stages, monitor errors and support tickets, and keep a tested recovery process for users who lose access.