How To Implement Passkeys with WebAuthn: Complete Developer Guide

Passwords have been the default way to authenticate users for decades, but they continue to create security and usability challenges. Users forget them, reuse them across services, and often store them insecurely. For developers, password-based systems mean account recovery queues, phishing risk, and credential breach exposure.

Passkey authentication is the modern alternative. This guide walks through how passkeys work, what the WebAuthn API looks like in practice, and what you need to build a complete passkey implementation — from registration to passkey login.

Understanding Passkeys

A passkey is a passwordless credential that lets users sign in with a trusted device — a smartphone, laptop, or hardware security key — instead of a password. Under the hood, passkeys use public-key cryptography:

During authentication, the server sends a random challenge to the device. The device signs it with the private key and returns the signature. The server verifies the signature using the stored public key. Because the private key never leaves the device, attackers can't steal it through phishing or server breaches.

Passkeys are built on the FIDO2 standard, which combines two components:

Why Developers Are Adopting Passkeys

Apple, Google, and Microsoft have all built passkey support into their platforms. Adoption is accelerating, and the reasons are practical:

Prerequisites

HTTPS and Browser Support

WebAuthn only works over HTTPS. Make sure your app is served with a valid TLS certificate — there are no exceptions, even in staging environments (use localhost for local development, which is exempted).

Modern browsers — Chrome, Safari, Firefox, and Edge — all support WebAuthn. You can check current coverage on caniuse.com.

Backend Infrastructure

Your server needs to handle three things:

Don't implement the cryptographic verification yourself. Use a well-maintained WebAuthn server library for your stack — for example, go-webauthn for Go, py_webauthn for Python, or @passwordless-id/webauthn for Node.js.

Account Recovery

Plan recovery before you launch. If a user loses their only registered device, they need a way back in. Common approaches: allow registering multiple devices, fall back to email verification, or support backup codes. Without a recovery path, locked-out users become support escalations — or lost customers.

How Passkey Authentication Works

Passkey authentication has two phases: registration (creating the credential) and passkey login (using it to sign in).

Registration Flow

Registration creates the key pair and links the public key to the user's account.

Passkey Login Flow

WebAuthn Example: Registration and Login

Here's what the WebAuthn API looks like in practice. Two browser methods handle everything.

navigator.credentials.create() — Passkey Registration

// Call your server to get a registration challenge first
const response = await fetch('/auth/passkey/register/begin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: currentUser.id }),
});
const options = await response.json();

// The server returns PublicKeyCredentialCreationOptions.
// The browser needs the challenge decoded from base64.
options.challenge = base64urlToBuffer(options.challenge);
options.user.id = base64urlToBuffer(options.user.id);

// Trigger the authenticator
const credential = await navigator.credentials.create({ publicKey: options });

// Send the new credential to your server to store
await fetch('/auth/passkey/register/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: credential.id,
    rawId: bufferToBase64url(credential.rawId),
    response: {
      attestationObject: bufferToBase64url(credential.response.attestationObject),
      clientDataJSON: bufferToBase64url(credential.response.clientDataJSON),
    },
    type: credential.type,
  }),
});

navigator.credentials.get() — Passkey Login

// Get an authentication challenge from your server
const response = await fetch('/auth/passkey/login/begin', { method: 'POST' });
const options = await response.json();

options.challenge = base64urlToBuffer(options.challenge);
// If you pass allowCredentials, decode each credential ID too
if (options.allowCredentials) {
  options.allowCredentials = options.allowCredentials.map(c => ({
    ...c,
    id: base64urlToBuffer(c.id),
  }));
}

// Prompt the user — browser handles biometric/PIN UI
const assertion = await navigator.credentials.get({ publicKey: options });

// Send the signed assertion to your server for verification
const verifyResponse = await fetch('/auth/passkey/login/complete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: assertion.id,
    rawId: bufferToBase64url(assertion.rawId),
    response: {
      authenticatorData: bufferToBase64url(assertion.response.authenticatorData),
      clientDataJSON: bufferToBase64url(assertion.response.clientDataJSON),
      signature: bufferToBase64url(assertion.response.signature),
      userHandle: assertion.response.userHandle
        ? bufferToBase64url(assertion.response.userHandle)
        : null,
    },
    type: assertion.type,
  }),
});

if (verifyResponse.ok) {
  // User is authenticated — redirect or update UI
}

The base64urlToBuffer and bufferToBase64url helpers convert between base64url strings (what your server sends) and ArrayBuffer (what the WebAuthn API expects). You'll need to implement these or use a library that handles the encoding for you.

Integrating with an Authentication Platform

Building WebAuthn from scratch is doable, but it's a significant surface area — challenge management, attestation validation, signature counter verification, multi-device sync, and more. Many teams use an authentication platform to handle this instead.

Authgear has built-in support for passkey registration and login. You connect your app to Authgear and the passkey flows — including the WebAuthn ceremony, credential storage, and device management — are handled for you. This is worth considering if your team's core product isn't authentication infrastructure. See how Authgear handles passkeys.

Testing Your Passkey Implementation

Test across environments before shipping:

Chrome DevTools has a WebAuthn emulator (DevTools → More tools → WebAuthn) that lets you test registration and authentication flows without a physical authenticator.

Best Practices

Register Multiple Devices

Encourage users to register at least two devices during onboarding. A user who only has one registered device and loses it will be locked out. Multiple devices — or a mix of a synced passkey plus a hardware key — provide a natural fallback.

Design Onboarding for Unfamiliar Users

Many users have never seen a passkey prompt. Show a brief explanation before triggering navigator.credentials.create(): what passkeys are, what will happen next, and that they're more secure than passwords. A confused user will hit cancel and never try again.

Generate Fresh Challenges Every Time

Every registration and login attempt must use a unique, server-generated random challenge (at least 16 bytes, ideally 32). Challenges must be single-use and short-lived (expire within 5 minutes). Reusing or accepting stale challenges opens the door to replay attacks.

Verify the Signature Counter

Authenticators maintain a signature counter that increments with each use. Your server should store and check this counter. If you receive a counter value lower than the stored one, it may indicate a cloned authenticator — flag it and require re-authentication.

Support Cross-Platform Passkeys

Passkeys can be device-bound (tied to one authenticator, like a hardware key) or synced (backed up via iCloud Keychain, Google Password Manager, or 1Password). Synced passkeys work across a user's devices automatically. Don't set authenticatorAttachment: "platform" if you want to allow hardware keys too.

Log Authentication Events

Keep server-side logs of registration attempts, successful logins, failed verifications, and credential deletions. These logs are essential for detecting anomalies — like repeated failed assertions against the same credential — and for debugging when users report problems.

Bottom Line

Passkeys replace shared secrets with cryptographic key pairs that stay on the user's device. The result is passkey authentication that's resistant to phishing, immune to credential breaches, and faster for users.

The WebAuthn API is well-supported in all modern browsers. The client-side code is straightforward; the complexity lives on the server — challenge management, assertion verification, and credential storage. Use a server library to handle the cryptographic heavy lifting rather than implementing it yourself.

If you'd rather not manage the infrastructure at all, Authgear provides passkey signup and login out of the box, so your team can focus on building the product instead of the authentication layer.

FAQs

What is passkey authentication?

Passkey authentication is a passwordless login method that uses public-key cryptography instead of passwords. The user's device holds a private key; the server stores the matching public key. At login, the server issues a challenge, the device signs it using the private key (after biometric/PIN verification), and the server confirms the signature. No password is ever created, stored, or transmitted.

What is a passkey?

A passkey is the credential created during passkey authentication. It consists of a cryptographic key pair: a public key on the server and a private key locked to the user's device. Users authenticate with biometrics or a device PIN — the private key never leaves the device.

How do passkeys work technically?

Passkeys use public-key cryptography. The device holds a private key; the server stores the corresponding public key. At login, the server issues a challenge, the device signs it with the private key, and the server verifies the signature. No shared secret is ever transmitted.

What is WebAuthn?

WebAuthn (Web Authentication API) is the browser API that applications use to create and use passkeys. It's a W3C standard supported in all major browsers.

Are passkeys more secure than passwords?

Yes. Passkeys can't be phished (they're domain-bound), can't be leaked in a server breach (only public keys are stored), and can't be reused across sites. They're also resistant to brute-force attacks since there's no secret to guess.

Can passkeys sync across multiple devices?

Yes. Apple (iCloud Keychain), Google (Password Manager), and Microsoft (Windows Hello) sync passkeys across a user's devices. Third-party password managers like 1Password and Dashlane also support passkey sync.

Is there a WebAuthn example I can run locally?

Yes. webauthn.io is an interactive WebAuthn demo you can test in your browser without any setup. For a local example, Google's Build your first WebAuthn app codelab walks through a full registration and authentication flow. The code examples in this article show the client-side WebAuthn calls you'd use in your own app.