Passkey basics · Implementation
The WebAuthn registration flow: what to check in challenge, options, and verify
7 min read
Key points
- Registration has three steps, in which the server builds options, the browser calls create(), and the server verifies and stores the result.
- The key options are a single-use challenge, a user.id with no personal data, excludeCredentials listing existing keys, and the residentKey and userVerification settings.
- Verification checks the type, challenge, origin, RP ID hash, flags, and algorithm, and confirms the credential ID isn't registered to anyone before storing it.
WebAuthn registration has three steps: your server builds options (including a challenge, the RP ID, and the user's ID), the browser has the authenticator create a passkey through navigator.credentials.create(), and your server verifies the response and stores the public key. Your server checks that the response is a registration, that the challenge is one it issued, that the origin and RP ID are right, the user presence and verification flags, the algorithm, and that the credential ID isn't already in use by another user. The procedure is defined in section 7.1, "Registering a New Credential," of W3C WebAuthn Level 3.
The overall flow
Browser Server (RP) Authenticator
| 1. start registration --> | |
| <-- 2. options | create and store a challenge |
| 3. create(options) ------------------------------------------>|
| | verify user, make key pair |
| <------------------------------------ 4. public key, signed data
| 5. send response ------> | 6. verify and store public key |Registration normally happens for a signed-in user, because your server decides whose passkey it is from its own session.
1. The server builds options
Your server builds the PublicKeyCredentialCreationOptions that go to navigator.credentials.create().
{
"rp": { "id": "example.com", "name": "Example" },
"user": {
"id": "<64 random bytes (base64url)>",
"name": "taro@example.com",
"displayName": "Taro Yamada"
},
"challenge": "<at least 16 random bytes (base64url)>",
"pubKeyCredParams": [
{ "type": "public-key", "alg": -8 },
{ "type": "public-key", "alg": -7 },
{ "type": "public-key", "alg": -257 }
],
"excludeCredentials": [
{ "type": "public-key", "id": "<existing credential ID>", "transports": ["internal"] }
],
"authenticatorSelection": { "residentKey": "preferred", "userVerification": "preferred" },
"attestation": "none",
"timeout": 300000
}What each field means:
| Field | Meaning |
|---|---|
rp.id |
The RP ID: the page's domain or a parent domain. The passkey only works within this scope |
rp.name |
The service name shown in the dialog |
user.id |
The user handle, at most 64 bytes. The spec says it must not contain personally identifying information such as a username or email, and recommends 64 random bytes |
user.name / displayName |
Names shown in the dialog and the user's passkey list |
challenge |
A random value from your server. The spec recommends at least 16 bytes. Store it server-side and use it once |
pubKeyCredParams |
Accepted signature algorithms. The spec recommends including at least -8 (EdDSA), -7 (ES256), and -257 (RS256) |
excludeCredentials |
The user's existing credentials, so the same authenticator doesn't get a second one |
authenticatorSelection.residentKey |
Whether to require a discoverable credential: required / preferred / discouraged |
authenticatorSelection.userVerification |
Whether to require biometric or PIN verification: required / preferred / discouraged |
attestation |
Whether to ask for proof of the authenticator's provenance. Defaults to none |
timeout |
A wait time in milliseconds. The spec treats it as a hint the browser may override |
Handling the challenge
The challenge proves the response was made for this registration. Store it server-side tied to the user (or session), delete it once used, and give it an expiry. Accepting the same challenge twice opens the door to replaying an old response.
Choosing residentKey and userVerification
- If username-less sign-in or autofill (conditional UI) will be your main entry point, set
residentKeytorequired. - Setting
userVerificationtorequiredblocks registration on authenticators that can't do biometrics or a PIN. Alternatively, usepreferredand record the UV flag at verification time.
Attestation
Attestation is an optional statement that lets the RP check an authenticator's make and provenance. With none, the browser replaces potentially identifying information with non-identifying values. Unless you need to allow only specific authenticators (for example, in an internal tool), none is enough.
2. The browser calls create()
Convert the server's JSON into what the browser API expects, then call it. PublicKeyCredential.parseCreationOptionsFromJSON() saves you from decoding base64url strings into ArrayBuffers yourself. MDN lists it as newly available across major browsers since March 2025, so for older browsers write the conversion yourself or use a library.
const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJSON);
const credential = await navigator.credentials.create({ publicKey });
await fetch('/api/passkey/register/verify', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(credential.toJSON()),
});The authenticator verifies the user (fingerprint, face, PIN) and creates a key pair for the RP ID. If it already holds a credential listed in excludeCredentials, it refuses.
The response mainly contains:
id/rawId: the credential IDresponse.clientDataJSON: what the browser recorded, including the type (webauthn.create), challenge, and originresponse.attestationObject: authenticator data (RP ID hash, flags, signature counter, credential ID, and public key) plus the attestationresponse.transports: how to reach the authenticator (internal,hybrid,usb, and so on)
3. The server verifies
Section 7.1 of W3C WebAuthn Level 3 lists the steps the RP performs, in order. In summary:
clientDataJSON.typeiswebauthn.create.challengematches the value you issued and stored for this session.originis an origin you accept (and, inside an iframe,topOriginis checked too).- The authenticator data's
rpIdHashequals the SHA-256 hash of your RP ID. - The UP (User Present) flag is set (the spec's only exception is registration with
mediationset toconditional). - If you require user verification, the UV (User Verified) flag is set.
- BS (Backup State) is not set when BE (Backup Eligibility) is unset.
- The public key's algorithm is one of those you listed in
pubKeyCredParams. - The attestation is verified according to its format and accepted or rejected per your policy (accepting
noneis a valid policy). - The credential ID is at most 1023 bytes.
- The credential ID isn't already registered to any user.
A library or an external API does this for you. Still, knowing what is checked makes errors easier to trace. Origin mismatches, for example, often come from mixing up RP ID or origin settings between test and production.
4. What to store
The spec lists the fields of the "credential record" the RP stores after a successful registration:
| Field | Used for |
|---|---|
id (credential ID) |
Identifying the key at sign-in |
publicKey |
Verifying signatures |
signCount |
The signature counter, a signal of possible cloning |
uvInitialized |
Whether the user was verified |
transports |
Telling the browser how to reach the authenticator next time |
backupEligible / backupState |
Whether it's syncable and currently backed up |
Add the user ID, a name ("iPhone"), the registration time, and the last-used time, and you'll have what you need for a device list and recovery screens.
Common mistakes
- Putting an email address in
user.id: This violates the spec and leaves personal data inside the authenticator. Use a random value. - Not passing
excludeCredentials: The same authenticator collects duplicate keys for one user, and they become indistinguishable in the list. - Reusing challenges: Always delete a challenge once it's been used for verification.
- Mismatched RP ID and origin: Make sure the page's domain equals the RP ID or sits under it.
Implementing with SealGate
With SealGate, the API builds the options and does the verification. For a signed-in user, your server makes two calls:
POST /v1/register/optionswith anexternal_id(an opaque ID) anddisplay_namereturnschallenge_idandoptions.options.excludeCredentialscontains the existing keys, andauthenticatorSelection.residentKeyanduserVerificationcome from the environment settings (resident_key,user_verification).- After the browser SDK (
sg.register()) runs the authenticator,POST /v1/register/verifywithchallenge_idandresponse(RegistrationResponseJSON) returns 201 withcredential_idandend_user_id. An optionalname(up to 64 characters) becomes the device label.
Challenges expire after 5 minutes and can be used once (410 challenge_expired). A failed signature check returns 401 verification_failed, and a response from an origin you didn't allow returns 403 origin_not_allowed. Adding a passkey for a user who already has one requires signed_in: true or a recovery_token. A duplicate on the same authenticator is refused by the authenticator, and the SDK reports it as already_registered. You can see each key's aaguid, transports, backup_eligible, and backed_up through GET /v1/users/{external_id}/credentials.
See the registration section of the docs for details.
FAQ
How long should the challenge be?
The WebAuthn spec recommends at least 16 random bytes. Generate it from a cryptographically secure source and use it once.
Is attestation "direct" more secure?
For consumer services, none rarely causes problems. Request attestation and define a verification policy only if you need to restrict which authenticators are allowed.
How is user.id different from the credential ID?
user.id is the user ID chosen by the RP and is shared by all of that user's passkeys. The credential ID is created by the authenticator for each key and differs for every passkey.
Sources
Related posts
Implementation
Choosing your RP ID and origins: passkeys across subdomains and domains
You can't change a passkey's RP ID later. How to choose an RP ID and allowed origins across subdomains and domains, and when related origin requests help.
Implementation · SealGate
How to add passkeys to an existing login without dropping passwords
A step-by-step plan for adding passkeys to a password login you already run, covering the RP ID, enrollment after sign-in, button and autofill sign-in, device management, recovery, and when to retire passwords.
Implementation · SealGate
Passkey sign-in with Next.js (App Router): Route Handlers and autofill
Add passkeys to an existing Next.js App Router login: relay options and verify in a Route Handler, issue your own session, and support autofill and a button.