Parameters and Data Structure Reference

This page is a field-level quick reference. For concept explanations, see Core Concepts; for usage, see Flows. Except where specifically noted, binary fields are ArrayBuffer/BufferSource in the browser API and are encoded as Base64URL (without padding) in JSON transmission by convention.

PublicKeyCredentialCreationOptions (Registration)

Passed to navigator.credentials.create({ publicKey }).

Field	Type	Required	Description
`rp`	Object	Yes	Relying party information. `rp.id` is the rpId (defaults to the registrable domain of current origin), `rp.name` is the display name.
`user`	Object	Yes	`user.id` (binary, opaque user handle, do not include PII like email), `user.name` (login name), `user.displayName` (display name).
`challenge`	BufferSource	Yes	One-time random challenge, ≥ 16 bytes.
`pubKeyCredParams`	Array	Yes	Algorithms acceptable to RP, ordered by preference; each item is `{ type: "public-key", alg }`, where `alg` is COSE identifier (see table below).
`timeout`	number	No	Milliseconds; 60000 recommended. Informational only; browser may ignore.
`excludeCredentials`	Array	No	List of already-registered credentials, preventing duplicate registration on the same authenticator. Each item is `{ type, id, transports? }`.
`authenticatorSelection`	Object	No	Authenticator filtering; see below.
`attestation`	string	No	`none` (default/recommended), `indirect`, `direct`, `enterprise`.
`extensions`	Object	No	Extensions, such as `credProps` (reports whether a resident key was created).

authenticatorSelection Sub-fields

Field	Values	Description
`authenticatorAttachment`	`platform` / `cross-platform`	Restricts to platform authenticators or roaming security keys; omit for no restriction.
`residentKey`	`required` / `preferred` / `discouraged`	Whether to create a discoverable credential (Passkey). `required` enforces resident.
`requireResidentKey`	boolean	Legacy field, retained for compatibility; `true` equals `residentKey: "required"`.
`userVerification`	`required` / `preferred` / `discouraged`	Whether to require user verification (UV).

PublicKeyCredentialRequestOptions (Authentication)

Passed to navigator.credentials.get({ publicKey }).

Field	Type	Required	Description
`challenge`	BufferSource	Yes	One-time random challenge.
`timeout`	number	No	Milliseconds, informational.
`rpId`	string	No	Relying party identifier, defaults to registrable domain of current origin; must match registration.
`allowCredentials`	Array	No	List of allowed credentials `{ type, id, transports? }`; leave empty for username-less Passkey login.
`userVerification`	string	No	`required` / `preferred` / `discouraged`.
`extensions`	Object	No	Authentication extensions.

clientDataJSON

Generated by the browser as JSON (returned as UTF-8 bytes); page JavaScript cannot tamper with it.

Field	Description
`type`	`"webauthn.create"` for registration, `"webauthn.get"` for authentication.
`challenge`	Base64URL encoding of the challenge issued by the RP.
`origin`	Complete origin of the page that initiated the request, such as `https://login.example.com`.
`crossOrigin`	Whether initiated from a cross-origin iframe, typically `false`.
`topOrigin`	Only appears if `crossOrigin` is `true`, the top-level origin.

Example:

{
  "type": "webauthn.get",
  "challenge": "YXV0aC1jaGFsbGVuZ2UtcmFuZG9t",
  "origin": "https://login.example.com",
  "crossOrigin": false
}

authenticatorData Structure

A binary data segment returned in both registration and authentication (in registration, encapsulated in attestationObject). Byte layout:

Offset	Length	Field	Description
0	32 B	`rpIdHash`	`SHA-256(rpId)`, must be verified by RP.
32	1 B	`flags`	Bit flags; see below.
33	4 B	`signCount`	Big-endian 32-bit signature counter.
37	Variable	`attestedCredentialData`	Only appears when `AT` flag is 1 (during registration); contains AAGUID (16B), credentialId length (2B), credentialId, credentialPublicKey (COSE).
After	Variable	`extensions`	Only appears when `ED` flag is 1, CBOR-encoded.

flags Bit Definitions

Bit	Name	Meaning
bit 0 (0x01)	`UP`	User Present, user is physically present.
bit 2 (0x04)	`UV`	User Verified, user has been verified (multi-factor).
bit 3 (0x08)	`BE`	Backup Eligible, credential can be backed up/synchronized.
bit 4 (0x10)	`BS`	Backup State, credential is currently backed up/synchronized.
bit 6 (0x40)	`AT`	Attested credential data included (set to 1 during registration).
bit 7 (0x80)	`ED`	Extension data included.

Tips

BE/BS distinguish synced Passkeys (cross-device) from device-bound credentials. If the business requires credentials to remain on device, check BE=0.

COSE Algorithm Identifiers

pubKeyCredParams[].alg uses COSE Algorithm values (IANA registry, all negative):

alg	Name	Description	Recommendation
`-7`	ES256	ECDSA + P-256 + SHA-256	First choice, nearly all authenticators support
`-8`	EdDSA	Ed25519	Optional if supported, good performance
`-35`	ES384	ECDSA + P-384 + SHA-384	Rare
`-36`	ES512	ECDSA + P-521 + SHA-512	Rare
`-257`	RS256	RSASSA-PKCS1-v1_5 + SHA-256	Compatibility with legacy TPM/Windows Hello, recommend providing alongside `-7`
`-258`	RS384	RSASSA-PKCS1-v1_5 + SHA-384	Very rare
`-259`	RS512	RSASSA-PKCS1-v1_5 + SHA-512	Very rare
`-37`	PS256	RSASSA-PSS + SHA-256	Some TPM

Tips

In practice, providing [-7, -257] covers the vast majority of authenticators: -7 (ES256) covers modern platforms and security keys, -257 (RS256) maintains compatibility with some Windows Hello / TPM scenarios.

Troubleshooting Quick Reference Table

Symptom / Error	Common Cause	Resolution
`SecurityError` (create/get)	`rp.id`/`rpId` is not the registrable domain of current origin; non-HTTPS (except localhost)	Correct rpId to registrable domain; use HTTPS
`NotAllowedError`	User cancelled, timeout, or origin/permissions policy not allowing	Prompt to retry; check `timeout` and `Permissions-Policy: publickey-credentials-*`
`InvalidStateError` (registration)	This authenticator already registered (matches `excludeCredentials`)	Prompt "this device already registered", guide to login
`ConstraintError`	`residentKey: required` or UV requirement authenticator cannot meet	Relax to `preferred`, or switch authenticator
Server challenge mismatch	Challenge not stored/expired; Base64URL decoding error	Store and bind challenge to session server-side; confirm Base64URL usage
Server origin verification failure	Missing origin from allowlist; protocol/port mismatch	Configure allowlist precisely
Signature verification failure	Signature data concatenation error (should be `authData ‖ SHA-256(clientDataJSON)`); algorithm mismatch with stored; ECDSA signature is DER-encoded, needs proper parsing	Review verification flow, prefer mature libraries
`signCount` always 0	Synced Passkey / certain platform authenticators	Treat as normal, don't reject based on this
Base64URL-related garbage	Mixed with standard Base64 `+//=`	Unify to Base64URL without padding for encoding/decoding

Related reading: Overview · Core Concepts · Registration and Authentication Flows. Multi-factor and federated login see ../mfa/, ../oidc/.