Passkey registration fails

A passkey is a key pair held by your device or security key: the private half never leaves the hardware, and the browser will only use it on the exact website it was created for. That last property is why passkeys resist phishing, and it is also why almost every registration failure in practice is an address problem rather than a hardware problem. This article gives you every error the ceremony can produce, verbatim, and tells you which are configuration, which are the browser protecting the user, and which are a wiring gap on our side that you cannot fix.

What a ceremony is, and where it can fail

Registration and sign-in each happen in two calls, called a ceremony: the first issues a random challenge, the second returns what the authenticator signed. Nothing is taken on trust from the browser — the credential identifier and the public key are read out of the signed data, so a caller cannot register a public key it does not hold.

POST /api/v1/auth/webauthn/register/begin      (signed in)
POST /api/v1/auth/webauthn/register/finish     (signed in)
POST /api/v1/auth/webauthn/assert/begin        (signed in — step-up)
POST /api/v1/auth/webauthn/assert/finish       (signed in — step-up)
POST /api/v1/auth/webauthn/login/begin         (public — passkey as a first factor)
POST /api/v1/auth/webauthn/login/finish        (public)
GET/PATCH/DELETE /api/v1/auth/webauthn/credentials[/{id}]

The two login routes are public because a passkey used as a primary factor is presented before any session exists. They name no user and return an empty credential list, so they cannot be used to find out which addresses have accounts.

The options we ask the browser for matter because they make some hardware refuse outright: a discoverable (resident) credential is required, the accepted algorithms are ES256, EdDSA and RS256 in that order, user verification is preferred rather than required by default, and the ceremony times out after 60 seconds. Requiring a discoverable credential is deliberate — a non-discoverable one cannot be used for username-less sign-in, which is the main reason to build passkeys at all. Very old security keys with no room for resident keys fail here and cannot be made to work.

Origin: the error you are most likely to see

The origin check is the phishing resistance. It compares the address the browser reports against a fixed list, and the failure message names the list for you — which is what makes it diagnosable without asking us for logs:

Read the two halves: the left is where the browser was, the right is what we accept. Any difference at all — a different hostname, a www. prefix, a custom domain in front of ours, an extra port, http instead of https — is a mismatch. The list is pinned to configuration rather than to the request's Host header, so an attacker cannot talk us into accepting their own origin with a forged header.

One nuance: a localhost origin is added only when the relying-party ID is literally localhost, so a production deployment cannot pick one up by accident — which is why a developer's working setup tells you nothing about whether your production hostname is right.

RP-ID pinning, and why moving domains breaks old passkeys

The relying-party ID is the domain a credential belongs to. It is stored on each credential, and on sign-in the check is made against that stored value rather than against a single global setting. A credential created under one domain therefore cannot be asserted under another, and the refusal is:

The practical consequence: if your Qorionix address changes, existing passkeys stop working and cannot be migrated. There is no rewrite, and there should not be — a credential that could be re-pointed at a new domain would be a credential an attacker could re-point too. Everyone re-registers. Plan for that before a domain change rather than after, and keep at least one administrator on a password plus an authenticator app until the new passkeys are in place.

Counter regression: a possible cloned authenticator

Most authenticators keep a counter that increases with every signature. If we see a counter that is the same as or lower than the last one we stored, the assertion is refused, because that is what a cloned device looks like:

Two honest caveats. An authenticator reporting zero on both sides is accepted, because a zero counter means the device does not implement the feature at all — so this check protects some hardware and not other hardware. And a benign cause exists: some platform authenticators synchronise a credential across a person's own devices and can present a lower counter than the one we last saw. Treat it as a possibility rather than a certainty, but do not wave it through — delete the credential, have them register a new one, and look at their recent sign-in history while you are there.

Every ceremony error, verbatim

Duplicate and unnamed credentials

Registration excludes the person's existing credentials, so the same authenticator cannot be silently enrolled twice — otherwise somebody ends up with three indistinguishable 'Security Key' entries and no way to tell which one they lost. If a re-registration is refused by the browser rather than by us, that exclusion is why. Rename credentials as you add them; a list of identical names is unusable at exactly the moment it matters.

• Passkeys and security keys — what they are and how to roll them out.
• MFA enrolment problems — the authenticator-app equivalent, including what to do when a device is lost.
• A user cannot sign in — if the block happens before the passkey prompt appears.