Passwords are the leakiest part of most applications. Users reuse them, attackers phish them, and support teams spend time resetting them. Passkeys—built on the WebAuthn standard—replace shared secrets with public-key cryptography, giving you fast, phishing-resistant sign-in that feels like Touch ID, Face ID, Windows Hello, or a security key. This guide explains how passkeys work, the server and data model you’ll need, UX patterns that avoid dead ends, how to migrate from passwords without locking users out, and how to roll it out safely in a modern web app.
What “passkeys” actually are
Passkeys are discoverable WebAuthn credentials. During registration, the browser and authenticator create a key pair that’s bound to your domain (the relying party ID). Your server stores the public key; the private key never leaves the user’s device or platform account. During sign-in, you send a challenge, the authenticator signs it, and your server verifies the signature against the stored public key. Because the credential is tied to your origin, phishing sites can’t use it.
Two ceremonies you’ll implement
- Registration (create credential): User proves who they are (usually via an existing session, verified email, or password), you return a creation challenge, the authenticator creates a key pair, and you persist the credential’s public key and metadata.
- Authentication (get assertion): User starts sign-in, you return a request challenge, the authenticator signs it, and you verify on the server. If valid, issue a session or token.
Terminology that matters
- Relying Party (RP) ID: The domain scope for WebAuthn (e.g., example.com). Credentials are bound to this.
- Credential ID: Opaque identifier for a specific passkey. You’ll store it and return it during auth.
- Sign counter: Monotonic counter to detect certain cloning scenarios (incremented by authenticators that support it).
- Transports: How the authenticator is accessed (internal, usb, nfc, ble). Useful for support and heuristics.
Server architecture and data model
You don’t store secrets with passkeys—only public keys and metadata—but you still need a few moving parts to make the flow reliable and secure.
Proposed data model
{ users: { id, email, ... }, passkey_credentials: { id, // internal DB id user_id, // FK -> users credential_id, // base64url public_key, // base64url or binary cose_algorithm, // e.g., -7 (ES256), -257 (RS256) if present sign_count, // integer (last known) transports, // array/json ("internal", "usb", ...) attestation_format, // optional; store if you process attestation aaguid, // authenticator model id (optional but useful) created_at, last_used_at, revoked_at // nullable; supports credential revocation }, webauthn_challenges: { id, user_id, // nullable for usernameless flows type, // "registration" | "authentication" challenge, // random base64url created_at, expires_at, request_context // json: origin, rpId, options snapshot } }Endpoints to implement
- POST /auth/passkeys/registration/start: Validate that the user is allowed to register (e.g., signed-in or has verified ownership of the email), generate a creation challenge, and return PublicKeyCredentialCreationOptions.
- POST /auth/passkeys/registration/finish: Verify the attestation response, persist the credential, and return success.
- POST /auth/passkeys/authentication/start: Generate a request challenge. For usernameless, return options with allowCredentials empty; for username-first, return the user’s known credential IDs.
- POST /auth/passkeys/authentication/finish: Verify the assertion, update sign_count and last_used_at, then issue a session or token.
Use well-maintained WebAuthn libraries on the server side to avoid low-level crypto mistakes, and always verify the origin, rpId, and challenge. Store challenges briefly (e.g., 5 minutes) and mark them as consumed after a successful assertion to reduce replay risk.
Picking the right UX: username-first, usernameless, or both
Passkeys enable smoother flows than passwords, but only if the UX fits your audience and deployment model. Choose deliberately.
Username-first (email, then passkey)
- Ask for email first. If the account has passkeys, offer “Use a passkey.”
- Pros: Familiar mental model; easy to layer alongside passwords and SSO.
- Cons: Slightly slower than a single-step “Continue with passkey.”
Usernameless (discoverable credentials)
- Offer “Sign in with a passkey” without asking for email first. The authenticator suggests accounts for your RP.
- Pros: Very fast; fewer steps; excellent on personal devices.
- Cons: Some environments disable discoverable credentials; cross-device prompts vary by platform; not all browsers expose the same UI affordances.
Hybrid with smart fallbacks
- Show “Continue with passkey” and “Continue with email.” If email is entered and has a passkey, prompt the passkey flow first, with password or magic link as fallback.
- Always display a clear escape hatch: “Try a different method.”
Security properties and pitfalls
- Origin-bound: Credentials won’t work on a phishing domain. Ensure your rpId is correct and stable.
- Replay-resistant: The signed challenge prevents replay. Never accept a reused or expired challenge.
- Sign counter: Update it and watch for decreases (possible cloning). Many authenticators now sync; not all maintain per-device counters.
- Attestation: Optional in most consumer apps. If you don’t need device attestation, reject or strip sensitive attestation info for privacy.
- Fallback safety: Phishing-resistant main method is undercut if your fallback is weak. Use strong second factors, magic links with short TTL, or backup codes.
Handling multi-tenant and custom domains
WebAuthn credentials are bound to an RP ID, usually a registrable domain like example.com. If your SaaS uses a single shared domain (app.example.com), this is straightforward. For custom domains (customer-a.com), passkeys registered on app.example.com won’t work at customer-a.com.
- One RP per domain: If tenants use custom domains, register and authenticate using their domain as rpId. Ensure the frontend initiates WebAuthn from that origin.
- Consistent origin: Avoid mixed flows where registration occurs on one domain and authentication on another; credentials won’t be discoverable.
- White-labeling: If you support bring-your-own-domain, scope WebAuthn to that domain and clearly communicate that passkeys won’t roam between domains.
Registration: safer entry criteria
Don’t let attackers bind credentials to accounts they don’t own.
- Require an authenticated session or a verified one-time token (e.g., magic link) before starting passkey registration.
- Enforce per-user limits (e.g., max N credentials) and expose management UI to remove lost or outdated passkeys.
- Store metadata like AAGUID and transports for support tooling, but avoid collecting anything you don’t need.
Authentication: verifying assertions correctly
- Challenge lookup: Fetch the stored challenge and ensure it matches the response and hasn’t expired or been used.
- Origin check: Verify the clientDataJSON origin equals your expected origin. Pay special attention in multi-domain deployments.
- RP ID hash: Confirm the authenticatorData rpIdHash matches your rpId.
- Signature verify: Use the stored public key and algorithm to verify the signature over the concatenated data.
- Counter update: If present, store the new sign counter; investigate regressions.
Recovery and fallback methods
Passkeys are excellent when users keep access to their device or platform account. Still, some users will lose access or be on devices without compatible support. Provide:
- Magic links with short expiration and single use.
- Backup codes users can store offline. Rotate on use.
- Authenticator apps (TOTP) if your risk model requires it.
- Help channels with verification steps for account recovery.
Migrating from passwords to passkeys
You don’t need a big-bang migration. Add passkeys alongside your current methods, then guide users to adopt them.
Practical migration steps
- Add passkeys as an additional sign-in option for already-authenticated users. Offer “Create a passkey” in Account Security.
- Just-in-time prompts: After successful sign-in via password or SSO, suggest creating a passkey. Keep it one click away.
- Prefer passkey-first on return visits: If the user has a passkey, show “Continue with passkey.” Provide a clear link to other methods.
- Gradually restrict high-risk actions (e.g., billing changes) to session re-auth with a passkey or strong second factor.
- Eventually make passkeys default and keep at least one secure fallback.
UI patterns that reduce confusion
- One button per intent: “Use a passkey” vs “Use email.” Avoid modal stacks that trap users.
- Explain what’s happening: A tiny line of text—“Your device will prompt you”—prevents misclicks.
- Credential management UI: List each registered passkey with last used date and remove controls.
- Cross-device clarity: If the system prompts for a phone, say why. Some platforms allow using a nearby device.
Testing plan: make failure modes boring
- Browser coverage: Test in current versions of major browsers on at least two platforms.
- Incognito/private mode: Expected behavior varies. Ensure clean fallbacks.
- Time skew: Your challenge expiration should not rely on client time.
- Concurrent prompts: Starting two challenges and finishing one should invalidate the other.
- Tenant domains: Verify registration and auth on both shared and custom domains.
- Analytics: Track initiation, success, and fallback rates to spot broken edges quickly.
Operational concerns: observability, logs, and privacy
- Audit trails: Log registration events, assertion attempts, success/failure reasons, and credential removals. Avoid sensitive payloads.
- PII minimization: Don’t store more attestation data than you need. Consider stripping attestation in consumer scenarios.
- Secrets management: WebAuthn reduces password risks but you still manage sessions, CSRF tokens, and other secrets.
- Feature flags: Gate passkeys per-tenant or per-segment to roll out safely.
Performance and reliability tips
- Short-lived challenges (e.g., 5 minutes). Clean up expired ones with a background job.
- Idempotent finishes: Registration finish should return success if the credential already exists for the user.
- Edge/session stores: If you’re at the edge, store challenges in a fast, replicated KV. Tag them with session IDs.
- Backoff and retries: Network hiccups happen mid-ceremony. UX should gracefully allow “Try again.”
Example flows and request shapes
The browser expects specific option objects for navigator.credentials.create() and navigator.credentials.get(). Your server returns those options, signed or at least traceable to a stored challenge. On completion, the client sends the full response to your server for verification.
// Registration start response (simplified) { "publicKey": { "rp": { "name": "Acme", "id": "app.acme.com" }, "user": { "id": "base64url-user-id", "name": "user@example.com", "displayName": "User Name" }, "challenge": "base64url-challenge", "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }], "authenticatorSelection": { "residentKey": "preferred", "userVerification": "preferred" }, "timeout": 60000, "attestation": "none" } }// Authentication start response (usernameless) { "publicKey": { "challenge": "base64url-challenge", "timeout": 60000, "rpId": "app.acme.com", "userVerification": "preferred", "allowCredentials": [] } }Building this with YeshBe
YeshBe is a platform for building software with AI. You describe what you want in natural language and refine it through conversation. You can implement passkeys by asking for the endpoints, database tables, and UI flows you need—then iterate on security, UX, and analytics. Here are realistic prompts that reflect what you might build:
Create passkey-based authentication using WebAuthn. Add endpoints:
POST /auth/passkeys/registration/start
POST /auth/passkeys/registration/finish
POST /auth/passkeys/authentication/start
POST /auth/passkeys/authentication/finish
Use app.example.com as the relying party ID for now. Persist challenges with a 5-minute TTL and single-use constraint. Implement server-side verification using a standard WebAuthn library.
Add a passkey_credentials table with fields: id, user_id, credential_id (base64url), public_key (base64url), cose_algorithm (int), sign_count (int), transports (json), aaguid (uuid, nullable), created_at, last_used_at, revoked_at. Add unique(user_id, credential_id).
On the Sign In page, add buttons: “Continue with passkey” and “Continue with email.” If the user has registered a passkey before, show the passkey button first. If passkey auth fails, show a message and reveal email + magic link fallback. Include a link to use a password if the account still has one.
In Account Security, add a section listing registered passkeys with display name (e.g., derived from authenticator AAGUID if available), last used, and a Remove button. Require a fresh passkey assertion to remove an existing passkey.
Add analytics for passkey flows: registration_started, registration_success, registration_error_reason, auth_started, auth_success, auth_error_reason, fallback_to_magic_link. Expose a small dashboard showing 7-day success rate and top error reasons.
Add tenant-aware support for custom domains. When the app is served on a custom domain, use that domain as rpId. Validate origins during verification accordingly. Include tests to confirm credentials are not usable across different domains.
Troubleshooting common issues
- “NotAllowedError” on create/get: Often user canceled or the browser blocked a modal. Provide a retry button and small helper text to check OS prompts.
- “InvalidStateError” on create: The credential already exists for that user. Treat as success or offer a rename.
- Empty account chooser: In usernameless flows, the user may have no discoverable credentials. Offer the email-first path.
- Verification fails intermittently: Check that you return the exact same challenge you stored, validate the correct origin, and enforce single-use challenges.
Rollout strategy for minimal risk
- Phase 1: Internal – Enable for your team only. Shake out UX and verification issues.
- Phase 2: Opt-in beta – Gate by a feature flag. Track success/failure metrics and common fallbacks.
- Phase 3: Default visible – Show “Continue with passkey” to all users who have one. Keep other methods prominent.
- Phase 4: Policy tightening – For sensitive actions, require a recent passkey assertion or strong fallback.
Accessibility and inclusivity
- Keyboard and screen readers: Ensure passkey buttons are focusable and labeled. Indicate when a device prompt is expected.
- Internationalization: Localize copy that explains passive OS prompts and fallback steps.
- No dead ends: Always present an alternative method.
When to require attestation
Most consumer-facing apps can set attestation to “none.” Consider attestation only if your risk model requires specific authenticator assurance (e.g., regulated environments). If you do process attestation, be explicit about what you store and why.
Putting it all together
Passkeys give you a faster, safer path than passwords without adding friction to everyday users. The key is choosing the right UX for your audience, implementing robust server verification, and rolling it out gradually with strong, well-communicated fallbacks. Start by adding passkeys for already authenticated users, track the success rate, and promote them to the default once the numbers look solid.
If you’re building with YeshBe, you can describe the endpoints, data model, and flows you want—then iterate with the AI on error handling, analytics, and multi-tenant domain rules. YeshBe is a platform for building software, so you remain in control of the architecture and rollout policy while speeding up the implementation details.