The Web Authentication API (WebAuthn) is a W3C standard that lets web applications authenticate users with public-key cryptography instead of passwords. It is the browser-facing half of the FIDO2 framework, which pairs WebAuthn with the Client-to-Authenticator Protocol (CTAP) to enable passwordless, phishing-resistant login across browsers and platforms. WebAuthn reached W3C Recommendation status in March 2019, and Level 3 of the spec entered Candidate Recommendation in January 2026 with support across Chrome, Firefox, Edge, and Safari.
\nThe problem WebAuthn solves is structural. Password-based authentication relies on shared secrets: the server stores a representation of your password, and you prove your identity by reproducing it. That model breaks in predictable ways. Credential stuffing, password spraying, and database breaches all exploit the same fundamental weakness. Even layering traditional MFA on top only raises the bar; it doesn’t change the underlying architecture. Authenticator app codes and SMS tokens are still shared secrets that can be intercepted through phishing, SIM swapping, or social engineering.
\nWebAuthn eliminates shared secrets entirely. When a user registers with a WebAuthn-enabled service, their device generates an asymmetric key pair. The private key stays on the device, locked inside a secure element or trusted platform module. The public key goes to the server. During authentication, the server issues a cryptographic challenge that only the correct private key can sign. No password crosses the wire. No secret is stored on the server to be stolen.
\nFour core concepts define how WebAuthn operates:
\nCredential. A credential is the public-key pair bound to a specific user and a specific origin (the website’s domain). Each credential is scoped so it can only be used on the origin where it was created. This origin binding is what makes WebAuthn phishing-resistant; a cloned login page at a different domain simply cannot trigger the correct credential.
\nAttestation. During registration, the authenticator can provide an attestation statement: a cryptographic proof that the credential was created by a genuine, trusted device. Attestation lets the server verify the authenticator’s make and model, which matters in regulated environments where only hardware-backed keys are acceptable.
\nAssertion. During login, the authenticator produces an assertion: a signed response to the server’s challenge that proves the user possesses the private key. The server validates this signature against the stored public key to complete authentication.
\nOrigin binding. The browser enforces that authentication requests are scoped to the exact origin (scheme + domain + port) that registered the credential. Even a pixel-perfect phishing site at a different URL will fail because the browser will not match credentials across origins. This protection operates at the protocol level, independent of user behavior or awareness.
\nTogether, these mechanisms create an authentication model where there is nothing to phish, nothing to replay, and nothing stored on the server worth stealing.
\nWebAuthn operates through two ceremonies: registration (creating a credential) and authentication (proving you own it). Both follow the same pattern. The server generates a challenge, the browser mediates the interaction with the authenticator, and the authenticator performs the cryptographic operation. Understanding these flows is essential before writing any integration code.
\nnavigator.credentials.create()Registration binds a new credential to a user account. The server initiates the process by generating a random challenge and specifying parameters about the relying party (your application) and the user.
\nconst credential = await navigator.credentials.create({\n publicKey: {\n challenge: serverGeneratedChallenge, // random bytes from your server\n rp: { id: \"example.com\", name: \"My App\" }, // relying party identity\n user: {\n id: userId, // unique user handle (ArrayBuffer)\n name: \"user@example.com\",\n displayName: \"Jane Developer\"\n },\n pubKeyCredParams: [\n { alg: -7, type: \"public-key\" }, // ES256 (recommended)\n { alg: -257, type: \"public-key\" } // RS256 (broad compatibility)\n ],\n authenticatorSelection: {\n userVerification: \"preferred\" // biometric/PIN if available\n },\n attestation: \"none\" // or \"direct\" for device verification\n timeout: 60000\n }\n});When this call executes, the browser prompts the user to interact with an authenticator: a fingerprint sensor, a security key tap, or a platform prompt like Windows Hello. The authenticator generates a new key pair, locks the private key inside its secure storage, and returns the public key along with a credential ID. Your frontend sends this response to the server for verification and storage.
\nnavigator.credentials.get()Authentication proves the user controls the private key registered earlier. The server sends a challenge and optionally a list of acceptable credential IDs.
\nconst assertion = await navigator.credentials.get({\n publicKey: {\n challenge: serverGeneratedChallenge,\n rpId: \"example.com\",\n allowCredentials: [{\n id: storedCredentialId, // from registration\n type: \"public-key\",\n transports: [\"usb\", \"ble\", \"internal\"] // hint for authenticator discovery\n }],\n userVerification: \"preferred\",\n timeout: 60000\n }\n});The authenticator locates the matching credential, verifies the user (biometric or PIN), and signs the challenge with the private key. The browser returns this signed assertion to your application, which forwards it to the server for signature verification.
\nThe server has three responsibilities across both ceremonies.
\nDuring registration, the backend must verify the attestation response. This means confirming that the challenge matches what was issued, the origin matches your application’s domain, and the public key uses an acceptable algorithm. Libraries like @simplewebauthn/server handle the cryptographic verification, but your application is responsible for storing the resulting credential data: the public key, credential ID, a signature counter, and the transports the authenticator supports.
During authentication, the backend verifies the assertion signature against the stored public key. It also checks the signature counter. Authenticators increment this counter with each use, so a counter value lower than or equal to the stored value signals a potential cloned credential. After successful verification, the backend updates the stored counter and issues a session.
\nThe step-by-step flow looks like this:
\nnavigator.credentials.create() or .get() with the challengeOrigin binding happens at step 3. The browser automatically includes the current origin in the data sent to the authenticator. If a user is on a phishing site at evil-example.com, the authenticator will not find a credential registered for that origin. The authentication fails silently, with no secret exposed to the attacker.
The WebAuthn standard has matured through three specification levels. Level 1 became a W3C Recommendation in March 2019, establishing the core API for credential creation and assertion. Level 2 followed in April 2021, adding support for cross-platform authenticator transports, improved attestation handling, and better alignment with the CTAP2 protocol. Level 3 reached Candidate Recommendation status in January 2026 and introduces features like the PRF extension for deriving encryption keys from credentials, conditional mediation (the ability to autofill passkey prompts), and the Signal API for relying parties to communicate credential state changes back to authenticators.
\nEach level builds on the previous one without breaking backward compatibility. If your application targets Level 2 features today, it will continue to work as Level 3 gains full browser adoption.
\nWebAuthn enjoys broad support across modern browsers. Chrome has supported it since version 67, Firefox since version 60, Edge since version 18, and Safari since version 13. On mobile, both Android (via Chrome and the platform credential manager) and iOS (via Safari with Face ID and Touch ID) provide full WebAuthn support. The practical result is that the vast majority of users on current browsers can use WebAuthn credentials without installing anything.
\nOne hard requirement: WebAuthn only works in secure contexts. That means HTTPS in production, no exceptions. The API will not execute over plain HTTP. For local development, localhost is treated as a secure context by browsers, so you can test without configuring TLS certificates on your dev machine. This requirement exists because origin binding is the foundation of WebAuthn’s phishing resistance, and origin verification is only meaningful over authenticated connections.
Browser support is not perfectly uniform across every feature. Platform authenticator availability depends on the operating system (Windows Hello, macOS Touch ID, Android biometrics), and newer Level 3 extensions like PRF are still rolling out across browsers and platforms. Implement feature detection using PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() and provide graceful fallbacks for users on older configurations.
WebAuthn did not appear in a vacuum. It evolved from FIDO U2F (Universal 2nd Factor), a protocol the FIDO Alliance introduced in 2014 for hardware-based second-factor authentication. U2F was effective but limited: it only functioned as a second factor alongside a password, it required a physical USB security key, and it never saw native Safari support.
\nWebAuthn addresses each of those limitations. It supports both multi-factor and single-factor (passwordless) authentication, so a fingerprint scan or security key tap can replace passwords entirely rather than just supplementing them. It works with platform authenticators built into devices, not only roaming USB keys. And it has universal browser adoption, something U2F never achieved.
\nThe transition is effectively complete. Chrome deprecated the U2F JavaScript API in version 98 and removed it entirely in version 115. Firefox deprecated U2F in favor of WebAuthn starting with version 60. Existing U2F security keys remain compatible with WebAuthn through CTAP1 backward compatibility, so users with older YubiKeys or Google Titan keys do not need to replace their hardware. For new implementations, WebAuthn through the FIDO2 framework is the only standard worth building on.
\nThe WebAuthn API surface is small, but the data flowing between client and server requires careful handling. The browser returns ArrayBuffer objects that need encoding before transmission. The server receives attestation and assertion structures that must be parsed, validated, and stored correctly. Here is a practical walkthrough of both sides.
Registration starts with your server generating options (challenge, user info, relying party config) and ends with the browser returning a new credential.
\nasync function registerCredential(userId: string): Promise<void> {\n // 1. Fetch registration options from your server\n const options = await fetch('/api/webauthn/register/options', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({ userId })\n }).then(res => res.json());\n\n // 2. Call the WebAuthn API\n const credential = await navigator.credentials.create({\n publicKey: {\n challenge: base64UrlToBuffer(options.challenge),\n rp: { id: options.rpId, name: options.rpName },\n user: {\n id: base64UrlToBuffer(options.userId),\n name: options.userName,\n displayName: options.userDisplayName\n },\n pubKeyCredParams: [\n { alg: -7, type: 'public-key' }, // ES256\n { alg: -257, type: 'public-key' } // RS256\n ],\n authenticatorSelection: {\n userVerification: 'preferred',\n residentKey: 'preferred'\n },\n attestation: 'none',\n timeout: 60000\n }\n }) as PublicKeyCredential;\n\n // 3. Send the response to the server for verification\n const attestationResponse = credential.response as AuthenticatorAttestationResponse;\n await fetch('/api/webauthn/register/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n id: credential.id,\n rawId: bufferToBase64Url(credential.rawId),\n response: {\n clientDataJSON: bufferToBase64Url(attestationResponse.clientDataJSON),\n attestationObject: bufferToBase64Url(attestationResponse.attestationObject)\n },\n type: credential.type\n })\n });\n}Authentication follows the same pattern. The server provides a challenge and optionally a list of allowed credential IDs, the browser collects the signed assertion, and the frontend forwards it.
\nasync function authenticate(): Promise<void> {\n const options = await fetch('/api/webauthn/login/options', {\n method: 'POST'\n }).then(res => res.json());\n\n const assertion = await navigator.credentials.get({\n publicKey: {\n challenge: base64UrlToBuffer(options.challenge),\n rpId: options.rpId,\n allowCredentials: options.allowCredentials?.map((cred: any) => ({\n id: base64UrlToBuffer(cred.id),\n type: 'public-key',\n transports: cred.transports\n })),\n userVerification: 'preferred',\n timeout: 60000\n }\n }) as PublicKeyCredential;\n\n const assertionResponse = assertion.response as AuthenticatorAssertionResponse;\n await fetch('/api/webauthn/login/verify', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n id: assertion.id,\n rawId: bufferToBase64Url(assertion.rawId),\n response: {\n clientDataJSON: bufferToBase64Url(assertionResponse.clientDataJSON),\n authenticatorData: bufferToBase64Url(assertionResponse.authenticatorData),\n signature: bufferToBase64Url(assertionResponse.signature),\n userHandle: assertionResponse.userHandle\n ? bufferToBase64Url(assertionResponse.userHandle)\n : null\n },\n type: assertion.type\n })\n });\n}Both flows depend on a pair of encoding helpers. The WebAuthn API works with ArrayBuffer, but JSON transport requires base64url strings.
function bufferToBase64Url(buffer: ArrayBuffer): string {\n return btoa(String.fromCharCode(...new Uint8Array(buffer)))\n .replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\n}\n\nfunction base64UrlToBuffer(base64url: string): ArrayBuffer {\n const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');\n const binary = atob(base64);\n return Uint8Array.from(binary, c => c.charCodeAt(0)).buffer;\n}The server’s job is to unpack the response, verify it cryptographically, and reject anything that does not match. For registration, that means parsing clientDataJSON to confirm the challenge and origin, then extracting the public key from the attestationObject. For authentication, it means validating the signature over the authenticatorData and clientDataJSON hash against the stored public key.
Libraries like @simplewebauthn/server handle the low-level CBOR decoding and signature math. Using one is strongly recommended over rolling your own verification.
const {\n generateRegistrationOptions,\n verifyRegistrationResponse,\n generateAuthenticationOptions,\n verifyAuthenticationResponse\n} = require('@simplewebauthn/server');\n\nconst RP_ID = 'example.com';\nconst ORIGIN = 'https://example.com';\n\n// Registration verification\nasync function handleRegistrationVerify(req, res) {\n const { body } = req;\n const expectedChallenge = await getStoredChallenge(req.session.userId);\n\n const verification = await verifyRegistrationResponse({\n response: body,\n expectedChallenge,\n expectedOrigin: ORIGIN,\n expectedRPID: RP_ID\n });\n\n if (verification.verified) {\n const { credential } = verification.registrationInfo;\n // Store the credential (see schema below)\n await saveCredential(req.session.userId, {\n credentialId: credential.id,\n publicKey: Buffer.from(credential.publicKey),\n counter: credential.counter,\n transports: body.response.transports || []\n });\n }\n}\n\n// Authentication verification\nasync function handleAuthVerify(req, res) {\n const { body } = req;\n const expectedChallenge = await getStoredChallenge(body.userId);\n const storedCredential = await getCredential(body.id);\n\n const verification = await verifyAuthenticationResponse({\n response: body,\n expectedChallenge,\n expectedOrigin: ORIGIN,\n expectedRPID: RP_ID,\n credential: storedCredential\n });\n\n if (verification.verified) {\n // Update counter to detect cloned authenticators\n await updateCredentialCounter(\n body.id,\n verification.authenticationInfo.newCounter\n );\n // Issue session\n }\n}Three fields inside clientDataJSON matter most during verification: type (must be webauthn.create for registration or webauthn.get for authentication), challenge (must match the server-issued value), and origin (must match your relying party origin exactly). If any of these fail, reject the response. Never trust req.headers.origin as your expected origin; hardcode it or load it from your server configuration.
Each user can register multiple credentials (a laptop fingerprint sensor, a phone, a backup security key), so your storage needs to support a one-to-many relationship between users and credentials.
\nCREATE TABLE webauthn_credentials (\n credential_id TEXT PRIMARY KEY,\n user_id TEXT NOT NULL REFERENCES users(id),\n public_key BYTEA NOT NULL,\n counter BIGINT NOT NULL DEFAULT 0,\n transports TEXT[], -- e.g. {'internal', 'usb'}\n created_at TIMESTAMP DEFAULT NOW(),\n last_used_at TIMESTAMP,\n friendly_name TEXT -- \"MacBook Touch ID\", \"Backup YubiKey\"\n);Track last_used_at so users can identify stale credentials in their account settings. Store transports so the browser can hint which authenticator type to prompt during login. Include a friendly_name column so users can distinguish between their registered devices. The counter column is your cloned-authenticator detection mechanism: if an authentication response arrives with a counter value less than or equal to the stored value, flag the credential and force re-registration.
WebAuthn is the strongest authentication mechanism available in browsers today, but you cannot assume every user has access to it. Some users are on older devices without biometric sensors. Some are logging in from a borrowed machine. Some work in environments where USB security keys are impractical. A production auth flow needs to handle all of these cases without degrading security for the users who can use WebAuthn.
\nThe right approach is progressive enhancement: offer WebAuthn when the device supports it, and fall back gracefully when it does not. The WebAuthn API provides the tools for this through feature detection.
\nasync function getAvailableAuthMethods() {\n const methods = ['password']; // baseline always available\n\n if (window.PublicKeyCredential) {\n methods.push('webauthn-roaming'); // security key support\n\n const platformAvailable =\n await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();\n\n if (platformAvailable) {\n methods.push('webauthn-platform'); // biometric/PIN support\n }\n }\n\n return methods;\n}PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() tells you whether the device has a built-in authenticator like Touch ID, Face ID, or Windows Hello. If it returns false, prompting for a platform authenticator will only confuse the user. Check first, then adapt the UI accordingly.
Conditional mediation, introduced in WebAuthn Level 3, takes this further. With navigator.credentials.get({ mediation: \"conditional\" }), the browser can surface passkey options in the autofill dropdown alongside saved passwords. Users who have registered a passkey see it as a login option without any extra UI. Users who have not registered one see the standard password field. No special prompts, no feature flags on your end.
When WebAuthn is unavailable or fails (the user cancels the prompt, a timeout occurs, the authenticator is not recognized), your application needs a clear fallback hierarchy. The goal is to maintain security while keeping the user moving forward.
\nA practical fallback chain looks like this:
\nasync function handleAuthFallback(userId, failedMethod) {\n const registeredMethods = await getUserMFAMethods(userId);\n\n if (failedMethod === 'webauthn' && registeredMethods.totp) {\n return { fallback: 'totp', message: 'Enter the code from your authenticator app.' };\n }\n\n if (registeredMethods.backupCodes > 0) {\n return { fallback: 'backup', message: 'Enter one of your recovery codes.' };\n }\n\n return { fallback: 'recovery', message: 'Contact support to verify your identity.' };\n}Each step down the chain accepts a weaker proof of identity, so the tradeoffs matter. TOTP codes are still strong second factors. Email and SMS one-time codes are vulnerable to interception but are better than locking a user out entirely. Recovery codes are single-use secrets that should be generated at enrollment time, stored offline by the user, and hashed on the server. Administrative recovery should require out-of-band identity verification and should be logged and auditable.
\nThe critical mistake is treating fallbacks as optional. Users will not register backup methods unless you build it into the enrollment flow. After a user registers their primary WebAuthn credential, prompt them immediately to set up a secondary method. Make it a required step, not a dismissible banner they will ignore.
\nNot every action in your application carries the same risk. A user browsing a dashboard does not need the same authentication assurance as one changing account credentials or approving a financial transaction. Progressive enhancement applies here too.
\nFor routine access, a valid session token is sufficient. For sensitive operations, trigger step-up authentication using the strongest method the user has registered. If they have a WebAuthn credential, require it. If they only have TOTP, require that. This layered approach lets you enforce strong authentication where it matters without adding friction to every interaction.
\nThe underlying principle is straightforward: make the secure path the default path, design the fallbacks honestly, and never let the absence of one method leave a user without any path forward.
\nImplementing WebAuthn from scratch means writing and maintaining challenge generation, CBOR parsing, attestation verification, signature validation, counter tracking, and credential storage. An auth framework handles that machinery for you and exposes WebAuthn as a configurable component. SuperTokens is a good example: it ships WebAuthn (passkeys) as a recipe in its Node.js and Python SDKs, so you enable it the same way you enable email/password or social login.
\nIn SuperTokens, authentication methods are “recipes” that you add to a recipeList. Adding passkey support means adding the WebAuthn recipe to both your backend and frontend initialization.
Backend (Node.js):
\nimport supertokens from \"supertokens-node\";\nimport Session from \"supertokens-node/recipe/session\";\nimport WebAuthn from \"supertokens-node/recipe/webauthn\";\n\nsupertokens.init({\n supertokens: { connectionURI: \"...\" },\n appInfo: {\n appName: \"Your App\",\n apiDomain: \"https://api.example.com\",\n websiteDomain: \"https://example.com\"\n },\n recipeList: [\n WebAuthn.init(),\n Session.init()\n ]\n});Frontend (React):
\nimport SuperTokens from \"supertokens-auth-react\";\nimport WebAuthn from \"supertokens-auth-react/recipe/webauthn\";\nimport Session from \"supertokens-auth-react/recipe/session\";\n\nSuperTokens.init({\n appInfo: {\n appName: \"Your App\",\n apiDomain: \"https://api.example.com\",\n websiteDomain: \"https://example.com\"\n },\n recipeList: [\n WebAuthn.init(),\n Session.init()\n ]\n});With those two changes, the framework wires up the API routes for credential options, signup, and signin. The core exposes endpoints like POST /recipe/webauthn/options/signin and POST /recipe/webauthn/signup, and the SDK handles the browser-side navigator.credentials calls and base64url encoding you would otherwise write yourself. If you use the prebuilt UI, the passkey registration and login screens render automatically. If you build custom UI, the SDK exposes functions that drive the same flows.
The recipe maps cleanly to the two WebAuthn ceremonies. On signup, the framework generates options, the SDK calls the authenticator, and the core verifies the attestation and stores the credential against the user. On signin, it generates a challenge, collects the assertion, verifies the signature, and updates the counter.
\nError handling is where framework integration earns its keep. WebAuthn surfaces a defined set of DOMException types: NotAllowedError when the user cancels or the prompt times out, InvalidStateError when a credential is already registered on the device, and NotSupportedError when the requested parameters are unavailable. The SDK normalizes these into status responses you can branch on, rather than leaving you to parse raw browser exceptions.
For fallback, you compose recipes rather than building a parallel system. Pair the WebAuthn recipe with email/password or passwordless (magic link / OTP) recipes in the same recipeList. Users on devices without passkey support authenticate through the alternate method, and the framework manages both paths under one user identity. You can also configure the relying party ID, attestation policy, and user verification requirements through the recipe’s customization options to match your security posture.
You rarely flip an existing user base to WebAuthn overnight. The realistic path is optional, incremental adoption layered on top of your current authentication.
\nStart by keeping your existing login intact and offering passkey registration as an opt-in inside account settings. After a user signs in with their password, prompt them to add a passkey for faster future logins. This builds a population of WebAuthn-capable accounts without forcing anyone through a migration wall.
\nOnce a user has registered a passkey, you can offer it as the default login method on their next visit while keeping the password available as fallback. Track adoption, and for high-value accounts (admins, users with elevated permissions), you can move from optional to required once enough of that cohort has enrolled.
\nIn SuperTokens specifically, this layering is handled by combining the WebAuthn recipe with your existing first-factor recipe, and optionally with the MFA recipe when you want WebAuthn enforced as a second factor for specific users or roles. The migration becomes a configuration and UX exercise rather than a rewrite of your auth layer.
\nWebAuthn removes entire categories of attack, but it introduces operational details that are easy to get wrong. The failures here are rarely cryptographic. They show up in attestation handling, credential lifecycle management, and error states that leave users stranded.
\nAttestation is the most commonly over-engineered part of a WebAuthn integration. It lets you verify the make and model of an authenticator, but most applications do not need it. Requesting attestation: \"direct\" pulls back identifying information about the user’s device, which raises privacy concerns and adds verification complexity you have to maintain. Unless you operate in a regulated environment that mandates specific hardware (FIPS-validated keys, for example), set attestation: \"none\". This respects user privacy and simplifies your server logic without weakening the core security guarantee.
User consent is built into the protocol through user presence and user verification. User presence (a touch or tap) confirms a human is physically present. User verification (biometric or PIN) confirms it is the right human. Set userVerification: \"preferred\" for most flows so the authenticator uses verification when available without hard-failing on devices that lack it. Reserve \"required\" for sensitive operations where you cannot accept presence alone.
Extensions like the PRF extension (for deriving encryption keys) or credProps (for learning whether a credential is discoverable) are powerful but unevenly supported. Treat them as enhancements, not dependencies, and always check the extension results rather than assuming they were honored.
WebAuthn credentials do not expire on their own, so revocation is your responsibility. Build a credential management interface where users can view their registered authenticators and remove ones they no longer control. When a user reports a lost device, revoking the corresponding credential should immediately invalidate it server-side by deleting the stored public key.
\nThere is no “rotating” a WebAuthn private key the way you rotate a password, because the key never leaves the authenticator. Rotation in practice means registering a new credential and revoking the old one. Encourage users to register a replacement before removing an old authenticator so they never drop to zero registered credentials.
\nA single registered authenticator is a single point of failure. If it is the only credential and the device is lost, the user is locked out. Make multi-device registration a deliberate part of onboarding: after a user registers their first credential, prompt them to add a second (a phone passkey alongside a laptop sensor, or a backup security key). Store credentials in a one-to-many relationship with the user, and let users assign friendly names so they can tell their devices apart when managing them later.
\nSynced passkeys (backed up through iCloud Keychain or Google Password Manager) reduce this risk because the credential follows the user across their devices. Device-bound credentials like hardware security keys do not sync, so backup registration matters more for those.
\nWebAuthn surfaces failures as DOMException types, and handling them gracefully separates a usable flow from a frustrating one.
try {\n const credential = await navigator.credentials.get({ publicKey: options });\n // verify on server\n} catch (err) {\n switch (err.name) {\n case 'NotAllowedError':\n // User canceled or the operation timed out\n showMessage('Authentication canceled. Try again or use another method.');\n break;\n case 'InvalidStateError':\n // Credential already registered on this device (during create)\n showMessage('This device is already registered.');\n break;\n case 'NotSupportedError':\n // Requested parameters not supported\n offerFallbackMethod();\n break;\n case 'SecurityError':\n // Origin or RP ID mismatch\n logSecurityEvent(err);\n break;\n default:\n offerFallbackMethod();\n }\n}NotAllowedError is the one you will see most. It covers both user cancellation and timeouts, so do not treat it as an attack signal. Give the user a clear path to retry or fall back. Authenticator removal mid-flow (unplugging a security key) also surfaces here. Always pair a timeout value with a fallback option so a stalled prompt never becomes a dead end.
Origin binding is what makes WebAuthn phishing-resistant: a credential registered for example.com cannot be used on evil-example.com, because the browser includes the real origin in the signed data and the authenticator will not match credentials across origins. A credential captured by a phishing site is useless because it was never issued for that origin in the first place.
That protection depends on configuring your relying party ID and expected origin correctly. The most common self-inflicted wound is loose origin validation on the server. Never derive your expected origin from the incoming request’s Origin header, because an attacker controls that value. Hardcode your allowed origins or load them from server configuration, and validate strictly.
// WRONG: trusting attacker-controlled input\nexpectedOrigin: req.headers.origin\n\n// CORRECT: server-defined allowlist\nconst ALLOWED_ORIGINS = process.env.NODE_ENV === 'production'\n ? ['https://example.com']\n : ['http://localhost:3000'];A mismatched or overly broad relying party ID (allowing wildcard subdomains, for instance) can also create silent failures or widen your attack surface. Set the RP ID to the registrable domain you actually serve, test it against your real origin, and resist the urge to loosen it to make a misconfiguration “work.”
\nWebAuthn is the strongest browser-based authentication available, but “strongest” does not mean “right for every situation.” Choosing it well means understanding what it beats, where it shines, and what it costs.
\nThe decisive difference between WebAuthn and every password-derived method is the shared secret. Passwords, OTP codes, and TOTP seeds are all secrets that exist in two places and can be intercepted, phished, or leaked. WebAuthn’s private key never leaves the authenticator, so there is nothing to intercept.
\n| Method | \nPhishing-resistant | \nShared secret | \nBreach exposure | \nUser friction | \n
|---|---|---|---|---|
| Password only | \nNo | \nYes | \nHigh (stored hashes) | \nLow | \n
| Password + SMS OTP | \nNo | \nYes | \nMedium (interceptable) | \nMedium | \n
| Password + TOTP | \nPartial | \nYes (seed) | \nMedium (seed theft) | \nMedium | \n
| WebAuthn | \nYes | \nNo | \nMinimal (public keys only) | \nLow to medium | \n
Against password-plus-SMS-OTP, WebAuthn wins decisively. SMS codes are vulnerable to SIM swapping and interception, and the password underneath remains phishable. TOTP (authenticator-app codes) is stronger because the code is generated locally and never transmitted as a long-lived secret, but the shared seed can still be stolen at enrollment, and a user can be tricked into typing a valid code into a phishing page. WebAuthn closes that gap entirely: even a user who wants to authenticate on a phishing site cannot, because the browser will not release a credential bound to a different origin.
\nCompared to traditional MFA generally, the difference is architectural rather than incremental. Traditional MFA stacks a second shared secret on top of the first. WebAuthn replaces the secret model with possession of a private key plus local user verification. That is why it resists the entire phishing and credential-stuffing class of attacks rather than just raising the cost.
\nWebAuthn is the strongest fit anywhere phishing resistance is a hard requirement. High-value targets benefit most: admin consoles, financial and healthcare applications, developer infrastructure, and any system where a compromised account causes serious downstream damage. It is also a strong choice for step-up authentication on sensitive operations, where you want cryptographic assurance for actions like changing credentials or approving transactions.
\nConsumer-facing products with broad device support are increasingly good candidates too, especially using synced passkeys. The login experience (a fingerprint or face scan) is often faster and smoother than typing a password plus an OTP code, so the security upgrade can actually reduce friction rather than add it.
\nDevice availability is the main constraint. Not every user has a biometric sensor or a security key, and users logging in from shared or borrowed machines may not have access to their authenticator. This is why a fallback path is mandatory rather than optional, as covered earlier.
\nAdoption friction is the second cost. Users are unfamiliar with passkeys, and account recovery becomes more involved when there is no password to reset. A lost device with no backup credential and no recovery method means a locked-out user. You absorb this cost through deliberate onboarding: prompt for a backup credential at registration, provide recovery codes, and keep a well-designed fallback chain in place.
\nThe practical answer for most teams is not “WebAuthn or nothing.” It is WebAuthn as the preferred, default method, backed by TOTP and recovery options for the cases where it is unavailable. You get phishing-resistant authentication for the users and moments that matter most, without locking out anyone who cannot use it yet.
\nFIDO2 is the overall framework; WebAuthn is one of its two components. FIDO2 combines WebAuthn (the W3C API that browsers and web applications use) with CTAP, the Client-to-Authenticator Protocol that handles communication between the device and external authenticators like security keys. In short, WebAuthn is what your web application calls, and CTAP is how the browser talks to the hardware. When people say “FIDO2 authentication,” they are usually describing the full passwordless experience that WebAuthn enables.
\nYes. iOS supports WebAuthn through Safari using Face ID and Touch ID, and Android supports it through Chrome and the platform credential manager using fingerprint and PIN. Both platforms back synced passkeys (iCloud Keychain on Apple devices, Google Password Manager on Android), so a credential registered on a phone can follow the user across their devices. Mobile is one of the strongest environments for WebAuthn precisely because nearly every modern phone ships with a built-in biometric authenticator.
\nYes. WebAuthn supports both single-factor (passwordless) and second-factor use. As a second factor, it replaces weaker options like SMS or TOTP with a phishing-resistant cryptographic check after a primary login. Many teams adopt it this way first, layering a WebAuthn security key or passkey on top of an existing password or social login, then move toward passwordless once adoption grows. Frameworks like SuperTokens let you configure WebAuthn as a required second factor for specific users or roles through their MFA recipe.
\nIt depends on the type of credential. Synced passkeys are backed up to your platform account (iCloud or Google), so they are recoverable on a new device by signing back into that account. Device-bound credentials, like hardware security keys, are not recoverable; the private key is gone with the device. This is why backup matters. A well-designed implementation prompts you to register a second credential at enrollment and provides recovery codes, so losing one authenticator never means losing access to your account. If you do lose your only credential with no backup, you fall back to the application’s account recovery process, which should require out-of-band identity verification.
\nWebAuthn looks complex from the spec, but adding it to a real application is mostly a matter of choosing the right tools and wiring them in. You do not need to implement CBOR parsing or signature verification yourself. Here is the fastest path from reading to shipping.
\nIf you are building the flow directly, @simplewebauthn is the most widely used option in the JavaScript ecosystem. It provides @simplewebauthn/server for backend verification and @simplewebauthn/browser for the frontend, handling the encoding and cryptographic work described earlier in this guide. For other stacks, the FIDO Alliance maintains a list of certified server libraries.
If you would rather not manage the auth layer at all, use a framework that ships WebAuthn as a configurable component. SuperTokens provides passkey support as a recipe in its Node.js and Python SDKs. Enabling it is a matter of adding WebAuthn.init() to your backend and frontend recipeList, as shown earlier. Because it is open source, you keep full visibility into the backend logic with no vendor lock-in, and you can self-host the core if you need to.
You do not have to rebuild your login to adopt WebAuthn. The lowest-risk starting point is to layer it on top of what you already have:
\nIn SuperTokens, this means composing the WebAuthn recipe alongside your existing first-factor recipe, and optionally the MFA recipe when you want it enforced as a second factor. The migration becomes a configuration and UX exercise rather than a rewrite.
\nFor deeper reference as you build:
\nThe shift away from shared secrets is already underway. Apple, Google, and Microsoft all support passkeys across their platforms, and the libraries and frameworks to implement WebAuthn are mature and well documented. Start by adding passkey registration as an option for your existing users, measure adoption, and expand from there. Phishing-resistant authentication is no longer a project reserved for large security teams; it is a recipe you can enable this week.
\n\n","frontmatter":{"date":"June 09, 2026","title":"What Is the WebAuthn API (and How to Use It in Your Auth Flow)","cover":"webauthn_api.png","author":"Maurice Saldivar","description":"Learn how the WebAuthn API enables passwordless, phishing-resistant login. Get step-by-step code and how to plug it into your auth stack."},"fields":{"slug":"/webauthin-api/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"0cd53134-8342-59a9-ac4c-111e9a524d36","fields__slug":"/webauthin-api/","__params":{"fields__slug":"webauthin-api"}}}, "staticQueryHashes": []}