Why passkeys now
Passwords are the biggest source of account takeovers, support tickets, and user friction. Passkeys let people sign in with a built‑in authenticator—Face ID, Windows Hello, or a phone prompt—without typing or remembering anything. They are phishing‑resistant, work across devices, and are supported by Apple, Google, and Microsoft.
But a passkey launch can still fail if the rollout is rushed. Users get confused by prompts. Developers miss edge cases. Support teams drown in “I lost my phone” tickets. This article is a practical blueprint to ship passkeys that feel simple, safe, and solid on day one.
What makes a passkey different
With passwords, the server stores a hash and compares it to what the user types. With passkeys, the server stores a public key, and the user’s device keeps the corresponding private key. When your app asks the device to sign a challenge, the device checks the user (biometric or PIN), signs, and returns a result your server can verify. No shared secret. No password reuse. No phishing pages getting the “secret.”
Two concepts matter for your rollout:
- Device‑bound vs synced passkeys. Device‑bound passkeys live on a specific hardware authenticator (like a security key). Synced passkeys live in a user’s platform credential manager and replicate across their signed‑in devices (iCloud Keychain, Google Password Manager, or Microsoft’s account). Most consumer flows prefer synced passkeys for easy recovery.
- Relying party ID (rpId). Passkeys are scoped to a domain. If your login moves from app.example.com to example.com, or your native app uses a different associated domain, sign‑in will fail. Choose your rpId early and stick to it.
Platforms you need to support
Browsers
On the web, passkeys use WebAuthn. You’ll present navigator.credentials.create to register a passkey and navigator.credentials.get to sign in. Browsers negotiate the right authenticator: platform (Face ID/Touch ID/Windows Hello) or a phone nearby. Modern desktop browsers also support passkey on another device with a QR code.
iOS and macOS
In native apps, use the platform’s APIs (e.g., ASAuthorizationController with passkeys). For web views, ensure you present passkey prompts via the system browser where possible. For associated domains, configure apple-app-site-association correctly so your native app can sync with the same rpId as your website.
Android
Use the Credential Manager API to request or create passkeys. It handles passkeys, passwords (during migration), and federated identity in one place. On the web, Chrome and other Chromium browsers provide WebAuthn with synced passkeys via Google Password Manager when the user opts in.
Designing the user journey
Where to offer passkeys
- Just‑in‑time after signup: After a successful email verification or social sign‑in, ask to “Save a passkey for faster, safer sign‑in.” Keep it optional but highly visible.
- At password login success: When a user signs in with a password, offer to “Replace your password with a passkey.” Make the benefit obvious.
- In account settings: Provide a clear “Passkeys” section showing registered credentials, devices, and removal options.
Copy that sets the right expectations
- Headline: “Sign in with your device—no password.”
- Body: “Your device stores a key that only it can use. We never see your biometric. You can use this on your other devices too.”
- Buttons: “Use a passkey” and “Try another method.” Avoid jargon like “WebAuthn” or “authenticator.”
Stop modal overload
Users often see back‑to‑back prompts: your UI, then a system dialog. Do not put a large modal behind a system modal. Use a light inline prompt with a single call‑to‑action, then let the system sheet take over. If the user cancels the system sheet, don’t show another popup; return to a simple page state with a small retry link.
Security defaults that actually stick
Server verification
On registration, store the credential ID, public key, and the signature counter. On sign‑in, verify the challenge, origin, rpId hash, and incrementing counter (when provided). Never trust any username returned by the client; map the credential ID to your account record on the server.
Transport and origin checks
- Enforce HTTPS everywhere, including subdomains and redirect targets.
- Set the rpId to the eTLD+1 you control (e.g., example.com) and keep it stable.
- Reject responses with unexpected origins, even if they contain a valid signature.
User verification is not optional
Set userVerification: “required” for sign‑in. This ensures a biometric or PIN gate. If you accept “preferred,” you may allow silent assertions in rare cases that weaken the protection.
Migrating from passwords without breaking sign‑in
Start hybrid, not rip‑and‑replace
Offer passkeys alongside passwords at first. Make passkeys the default call‑to‑action when a user is eligible, but keep “Use password instead” as a small link. Your goal is to reduce friction, not force a new habit overnight.
Eligibility rules
- If a user has a verified email or phone, you can offer passkey enrollment.
- If a user is on a shared or public device (kiosk), hide passkeys for that session.
- If the domain or app is in a testing/staging environment, ensure rpId is distinct to avoid polluting real credentials.
Handling multiple accounts on one device
Let users choose among discovered accounts. Populate the user handle at registration (a stable, opaque UUID) so credentials are “discoverable.” On sign‑in, the system may show the account chooser. In your UI, make account switching explicit and easy.
Recovery that doesn’t undo the security
The baseline: synced passkeys
For most consumers, synced passkeys are enough. If a phone is lost, a new phone signed into the same cloud account will restore the credential after step‑up verification by the platform. Your app does not handle the cryptography; you trust the platform sync.
Layered backups for higher assurance
- Security keys: Offer adding a hardware key as a backup authenticator for high‑value accounts.
- Recovery codes: Provide single‑use recovery codes. Show them once, store hashed, and encourage printing.
- Trusted devices: Allow approving a new device from a signed‑in session with a high‑friction, time‑delayed flow.
What to avoid
Don’t default to SMS for recovery. It helps during migration but is vulnerable to SIM swap and phishing. If you must support SMS, treat it as a step‑up to restore access after an email‑verified action or a helpdesk workflow, not as a standalone authentication method.
Native apps, web, and cross‑device sign‑in
Cross‑device magic
Modern browsers and devices support signing in by scanning a QR code with a phone that has a passkey. The phone shows a biometric prompt and sends the assertion over an encrypted channel to the desktop. This is built‑in—no QR spec of your own is required—so long as your WebAuthn get() request allows “hybrid” authentication.
Associated domains for native apps
To share passkeys between your site and your native app, set up associated domains and the right app manifests. This makes “Sign in with passkey” appear inside the app, using the same rpId as the site. Test this with clean installs and with multiple user accounts.
Handling incognito and restricted profiles
In private browsing or on managed devices, passkeys may be blocked or not discoverable. Detect the error gracefully and fall back to password + code or email link. Remember: never dead‑end the user.
Attestation and privacy
Do you need attestation?
Attestation proves what kind of authenticator created the passkey. It’s useful for high‑assurance enterprise cases or regulated flows. For most consumer apps, attestation adds little value and can leak device details. If you don’t need it, set attestation: “none”.
When to require it
- Workforce SSO where device trust is enforced.
- Regulatory contexts with hardware key policies.
- Very high‑risk financial operations with tiered controls.
Metrics that tell you the truth
What to track
- Prompt exposure rate: How often did eligible users see “Use a passkey”?
- Enrollment completion: How many started and finished passkey creation?
- Sign‑in success: Share of successful “get()” responses per attempt.
- Cancel/abort reasons: User canceled vs. not available vs. not allowed.
- Fallback usage: Password or code usage after a failed passkey attempt.
- Ticket volume: Lost device, new device, or “prompt didn’t appear.”
A/B tests that matter
- Button emphasis: “Use a passkey” as primary vs. secondary.
- Placement timing: after password success vs. at signup vs. in settings.
- Copy variants: “No password needed” vs. “Sign in with your device.”
Engineering pitfalls and how to avoid them
rpId mismatches
If you register a passkey on www.example.com and later try to sign in from login.example.com with rpId set to example.com, some credentials won’t match. Decide early: use the top‑level domain (example.com) if you need subdomain flexibility. Verify that your origin and rpId logic is consistent across all code paths.
Non‑discoverable credentials
If you skip “resident/ discoverable” credentials at registration, sign‑in may require a username first. Prefer discoverable credentials with a stable user handle. This enables the cleanest one‑tap sign‑in and cross‑device QR flows.
Poorly managed counters
Some authenticators provide a signature counter. If you store it, update it. If verification fails because of a counter error, do not lock out the account. Log and investigate; treat the counter as a weak signal, not a sole lockout trigger.
Not handling multiple credentials
Users can register multiple passkeys (phone, laptop, hardware key). Your server model must allow multiple credential IDs per user and provide a clean UI to manage and remove them.
Support playbook for day one
Fast triage questions
- What device and browser? (Some older ones do not support synced passkeys.)
- Are you on a shared computer or private mode?
- Which domain or app screen are you on?
- Do you see “Use a passkey” or only “Use password”?
Common fixes
- Try the system browser (Safari/Chrome) instead of a third‑party web view.
- Sign into the device’s account sync (iCloud/Google/Microsoft).
- If using desktop, choose “Use a phone” and scan the QR with your mobile.
- If nothing works, fall back to password + code, then offer passkey enrollment after success.
Communication templates
Write short, direct help messages:
- “Lost my phone”: “Use your laptop’s passkey or a recovery code. If unavailable, use password + email link, then add a new passkey in Settings.”
- “Prompt doesn’t appear”: “Check you’re on https://example.com and not in private browsing. Click ‘Try another method’ to sign in, then re‑enable passkeys from Settings.”
Fraud and risk: keep the bar high
When to step up
Passkeys are strong, but behavior still matters. Trigger step‑up when:
- New device, high‑risk location, or impossible travel.
- High‑value actions (payouts, admin changes).
- Unusual API patterns (session hijack signals).
Step‑up can be another passkey, a hardware key, or a recovery code—not SMS unless you must.
Session security
Use short‑lived tokens and refresh with device‑bound checks. Rotate refresh tokens on reuse detection. Bind sessions to additional signals (e.g., user agent family, not a strict fingerprint). Offer session review in account settings: “Signed in on iPhone 15, last used 2 hours ago.”
Enterprise and regulated contexts
Device compliance
Workforce SSO often requires attestations, managed device posture, or hardware keys. Integrate passkeys with your IdP and device management solution. You may require device‑bound credentials only, disable sync, and enforce TPM/SE presence.
Break‑glass access
Keep a break‑glass path with audited, time‑bound elevation using offline recovery codes or hardware tokens held in secure custody. Document the process in runbooks and test quarterly.
A simple technical blueprint
Registration (create)
- Server generates a random challenge and returns WebAuthn “create” options with rpId, user handle, discoverable preference, and pubKeyCredParams.
- Client calls navigator.credentials.create or the native API. User approves with biometric/PIN.
- Client returns the credential: id, public key, attestation (optional), and transports.
- Server verifies the attestation (if required), origin, rpId hash, and challenge. Stores credential.
Authentication (get)
- Server sends a fresh challenge with rpId and userVerification: “required”.
- Client calls navigator.credentials.get. The system may show account choices or QR code for a phone.
- Client returns assertion with signature and authenticator data.
- Server verifies signature against the stored public key, checks challenge and origin, updates counter.
Credential lifecycle
- List credentials in settings with device labels (e.g., “iPhone,” “MacBook”).
- Allow removal. If all are removed, prompt to add a new passkey next sign‑in.
- Log sign‑ins by credential ID for investigations and user transparency.
UX patterns that reduce confusion
Do
- Use clear affordances: A key icon with “Use a passkey.”
- Provide a small “Other methods” link: Never trap the user.
- Confirm success: “You added a passkey on this device. You can use it on your other signed‑in devices too.”
- Explain privacy: “We do not store your biometric or see it.”
Don’t
- Don’t call them “webauthn tokens” or “resident credentials.”
- Don’t show scary warnings when a user cancels the system prompt.
- Don’t block on attestation unless you have a policy need.
Testing matrix you actually need
Browsers and devices
- iOS Safari and iPadOS with passkey sync on/off.
- Android Chrome with Credential Manager enabled and disabled.
- macOS Safari and Chrome; Windows Chrome and Edge; at least one Linux browser.
- Cross‑device QR flows: iPhone → Mac; Android → Windows; Android → Mac.
Scenarios
- Registration and sign‑in on the same device.
- Sign‑in on a new device via synced passkey.
- Incognito/private browsing fallback.
- Account with two passkeys and one removal.
- Domain changes: subdomain → apex and vice versa.
Rollout plan in four phases
Phase 1: Internal and beta
- Enable passkeys for staff on staging with separate rpId.
- Finalize copy and the post‑success enrollment prompt.
- Instrument metrics and error logging.
Phase 2: Opt‑in for early adopters
- Gate with a feature flag. Offer in settings first; announce in release notes.
- Collect feedback on missing prompts and recovery confusion.
- Train support with a short decision tree and canned responses.
Phase 3: Default on for eligible users
- Make “Use a passkey” the primary button when possible.
- Keep password link, but de‑emphasized.
- Monitor success rate and fallbacks daily. Fix rpId and web view gotchas quickly.
Phase 4: Reduce passwords
- Introduce passwordless default for new accounts.
- For existing accounts with a passkey, show password fields only behind an “Other methods” expander.
- Plan a long‑tail deprecation of passwords with clear in‑product education.
Frequently asked questions
Can families share passkeys?
Some platforms allow sharing credentials within a family group. Treat this as a convenience, not as an enterprise delegation model. Your app should still separate user accounts; do not rely on shared passkeys for access control outside personal contexts.
Do passkeys work offline?
The device can sign offline, but your app must verify server‑side. Avoid offline sign‑in unless your product has a strict offline mode with local accounts and later sync.
What if my app has multiple brands?
Create a stable rpId per brand (e.g., brandA.com, brandB.com). If you use a shared login domain, align all frontends to that origin to avoid user confusion and credential splits.
Summary:
- Passkeys replace passwords with phishing‑resistant, device‑based sign‑in that feels natural.
- Pick a stable rpId, default to discoverable credentials, and require user verification.
- Offer passkeys alongside passwords first; promote them after successful sign‑in.
- Rely on synced passkeys for consumer recovery, with optional backups like security keys and recovery codes.
- Design a calm UI: one inline prompt, clear privacy notes, and easy fallback.
- Support cross‑device sign‑in with built‑in QR flows; set up associated domains for native apps.
- Track enrollment and success metrics, handle aborts gracefully, and avoid lockouts on edge cases.
- Roll out in phases: internal, opt‑in, default on, then gradually de‑emphasize passwords.
