Set up passkeys: the minimum server checks
Generate fresh challenges, bind them to the ceremony, and verify origin, RP ID, flags and signatures before creating a session or storing a credential.
Use a maintained WebAuthn verifier and keep ceremony state on the server. Registration establishes a credential’s public key; authentication proves possession of its private key. A successful browser prompt does not establish either fact to your server until you verify the returned response.
Send options, not secrets
These are illustrative JSON response bodies, not reusable challenges. Generate a fresh unpredictable challenge for every ceremony, store it with an expiry, ceremony type and intended session, then consume it once. Registration also needs an authenticated account or an appropriately protected enrollment flow.
{
"challenge": "REPLACE_WITH_FRESH_BASE64URL_RANDOM_BYTES",
"rp": { "id": "example.com", "name": "Example" },
"user": {
"id": "b3BhcXVlLXVzZXItMTIz",
"name": "ana@example.com",
"displayName": "Ana"
},
"pubKeyCredParams": [
{ "type": "public-key", "alg": -7 },
{ "type": "public-key", "alg": -257 }
],
"authenticatorSelection": {
"residentKey": "required",
"userVerification": "required"
},
"attestation": "none",
"excludeCredentials": []
}
Use an opaque stable account ID as user.id, encoded as base64url in JSON. Populate excludeCredentials from that account’s existing credential IDs to discourage duplicates. For username-less sign-in, an authentication response body can be:
{
"challenge": "REPLACE_WITH_ANOTHER_FRESH_CHALLENGE",
"rpId": "example.com",
"userVerification": "required",
"allowCredentials": []
}
An empty allowCredentials permits discoverable credentials; a username-first flow can list that user’s allowed credential IDs instead. If the ceremony’s allowCredentials was non-empty, require the returned credential ID to be in that list. If no user was identified beforehand, require a present, non-null userHandle that maps to the account owning the returned credential. If a user was identified beforehand, require the credential to belong to that account and any supplied userHandle to match that account’s handle. Keep the issued allowlist with the server-side ceremony state.
The native browser methods expect binary buffers for challenge and IDs. Use PublicKeyCredential.parseCreationOptionsFromJSON() and parseRequestOptionsFromJSON() where supported, or a library’s JSON conversion. Do not pass base64url strings straight into navigator.credentials.create() or get() as binary fields.
Verify before persisting or logging in
| Check | Registration | Authentication |
|---|---|---|
| Ceremony and challenge | webauthn.create, stored challenge, unused and unexpired |
webauthn.get, stored challenge, unused and unexpired |
| Origin | Exact trusted origin including scheme and non-default port | Same exact-origin policy |
| Embedding context | Check crossOrigin and validate any topOrigin against approved embedding origins |
Same checks for authentication |
| RP binding | rpIdHash equals SHA-256 of the configured RP ID |
Same, unless an explicitly supported extension changes the rule |
| Flags | User presence; user verification when required; valid backup flags | Same, plus stored backup-eligibility consistency |
| Cryptographic validation | Parse attestation/authenticator data, validate algorithm and attestation per policy | Verify signature over authenticatorData plus SHA-256 of exact clientDataJSON bytes |
| Credential record | Store credential ID, public key, algorithm, counter and backup metadata; reject duplicate ownership | Look up the stored key and verify account ownership; update state after success |
Do not derive the expected origin or RP ID from untrusted request headers. RP ID is a domain, without scheme, port or path; origin includes scheme and port. https://login.example.com can use RP ID example.com when permitted, but the expected origin remains the exact login origin. A suffix string comparison is not a sufficient origin policy.
For both registration and authentication, if clientDataJSON.crossOrigin is true, reject the response unless you explicitly allow ceremonies in a cross-origin iframe. If topOrigin is present, require that embedding is expected and that it exactly matches an approved top-level embedding origin. Checking only the iframe’s origin does not approve its parent. A site that does not support cross-origin embedding should reject either signal of an unexpected embedding context.
With SimpleWebAuthn 14.1.0, configure expectedOrigin for both verifiers and expectedTopOrigin for approved authentication embedding origins. Registration has no expectedTopOrigin option in this version: enforce its embedding policy in application code on the decoded clientDataJSON, then run the normal verifier on the original response. Also enforce your application’s crossOrigin policy for authentication; do not rely on expectedTopOrigin alone to reject every unexpected context, including responses missing topOrigin. These checks supplement signature verification rather than replace it. See the cross-origin guide.
A zero counter is valid for authenticators that do not implement counters. If either stored or received counter is nonzero and the new value does not increase, evaluate your clone/race risk policy. Synced passkeys cannot all be required to behave like a single device with a strictly increasing counter.
Choose a verifier with a current API
As checked against the npm registry in November 2026, @simplewebauthn/server is 14.1.0 and requires Node 22 or newer. Pair it with @simplewebauthn/browser (14.0.0 in the same registry check), whose helper names include startRegistration and startAuthentication. Server functions include generateRegistrationOptions, verifyRegistrationResponse, generateAuthenticationOptions and verifyAuthenticationResponse. Current authentication verification accepts a credential record; old examples using an authenticator argument predate the current API. See the server documentation and browser documentation.
Reject failed verification before issuing cookies. Persist challenge consumption and credential state with concurrency in mind. Adding a passkey, deleting the last one, and account recovery need their own account-security policy; possession of a newly created credential does not authorize attaching it to any account.
The normative checklists are in WebAuthn Level 3, registration and authentication. Go deeper with the passkey verification dive.