Complete passkey registration

POST/api/auth/webauthn/register/finish

webauthnRegisterFinish

Sudo-gated. Verifies the authenticator's attestation response against the stored ceremony and persists the credential. The `challenge_id` must be one this account started for registration: a challenge minted by the login or sudo endpoints is refused, as is one belonging to another account.

Requires authentication using a session cookie — see tokens and scopes.

curl

curl -X POST 'https://neosource.dev/api/auth/webauthn/register/finish' \
  -b 'ns_session=$NEOSOURCE_SESSION' \
  -H 'Content-Type: application/json' \
  -d '{"challenge_id":"string","response":"string"}'

fetch

fetch("https://neosource.dev/api/auth/webauthn/register/finish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({"challenge_id":"string","response":"string"}),
});

Request bodyrequired

application/json

PasskeyRegisterFinishRequest

object

Completes registration with what the authenticator produced.

challenge_idrequired: string
label: string | null
Optional display name. Defaults to something derived from the user agent ("Passkey on Firefox") so the list never shows a blank row. Truncated to 64 characters.
responserequired: The `PublicKeyCredential` returned by `navigator.credentials.create()`, serialised to JSON.

additional propertiesnot allowed

Responses

200Passkey registered

application/json

PasskeySummary

object

One registered authenticator, as shown in `/settings/security`.

created_atrequired: integerint64
Millis since epoch.
credential_idrequired: string
Base64url (unpadded) credential ID — the handle for rename and delete. Opaque; do not parse.
labelrequired: string
last_used_at: integer | nullint64
Millis since epoch; absent until the passkey is first used.
transports: string | null
Comma-separated transport hints the browser reported at registration (`"usb,nfc,hybrid,internal"`), when it reported any. Advisory only — used to pick an icon.

403Sudo required — the `challenge` field names which sudo-prove endpoint to call

application/json

SudoRequiredError

object

Wire shape of the 403 a sudo-gated endpoint returns when sudo is missing or expired. `challenge` tells the SPA which sudo-prove endpoint to call.

challengerequired: string
Which sudo-prove endpoint the account should use: `"passkey"` (`/api/auth/sudo/passkey/{start,finish}`), `"password"` (`/api/auth/sudo/password`), or `"totp"` (`/api/auth/sudo/totp`), chosen from the account's registered credentials — passkey first when present, since it is both the strongest credential and the least friction. A hint for which prompt to show first, not an authorization decision: each sudo route verifies its own credential regardless of what was advertised here, so a client may use a different one.
errorrequired: string
Always `sudo_required` — this body exists to carry the extra fields that kind needs.
"sudo_required"
messagerequired: string

Standard errors

Bodies documented once for the whole API — see standard errors.

400Malformed or unverifiable authenticator response
401Authentication required
409This authenticator is already registered
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget