ThePublicKeyCredentialCreationOptions dictionary represents the object passed toCredentialsContainer.create() as the value of thepublicKey option: that is, when usingcreate() to create a public key credential using theWeb Authentication API.

Instance properties

attestationOptional

A string specifying the relying party's preference for how the attestation statement (i.e., provision of verifiable evidence of the authenticity of the authenticator and its data) is conveyed during credential creation. The value can be one of the following:

"none"

Specifies that the relying party is not interested in authenticator attestation. This might be to avoid additional user consent for round trips to the relying party server to relay identifying information, or round trips to an attestation certificate authority (CA), with the aim of making the authentication process smoother. If"none" is chosen as theattestation value, and the authenticator signals that it uses a CA to generate its attestation statement, the client app will replace it with a "None" attestation statement, indicating that no attestation statement is available.

"direct"

Specifies that the relying party wants to receive the attestation statement as generated by the authenticator.

"enterprise"

Specifies that the Relying Party wants to receive an attestation statement that may include uniquely identifying information. This is intended for controlled deployments within an enterprise where the organization wishes to tie registrations to specific authenticators.

"indirect"

Specifies that the relying party wants to receive a verifiable attestation statement, but it will allow the client to decide how to receive it. For example, the client could choose to replace the authenticator's assertion statement with one generated by an Anonymization CA to protect user privacy.

Ifattestation is omitted, it will default to"none".

attestationFormatsOptional

An array of strings specifying the relying party's preference for the attestation statement format used by the authenticator. Values should be ordered from highest to lowest preference, and should be considered hints — the authenticator may choose to issue an attestation statement in a different format. For a list of valid formats, seeWebAuthn Attestation Statement Format Identifiers.

If omitted,attestationFormats defaults to an empty array.

authenticatorSelectionOptional

An object whose properties are criteria used to filter out the potential authenticators for the credential creation operation. This object can contain the properties:

authenticatorAttachmentOptional

A string indicating which authenticator attachment type should be permitted for the chosen authenticator. Possible values are:

"platform"

The authenticator is part of the device WebAuthn is running on (termed aplatform authenticator), therefore WebAuthn will communicate with it using a transport available to that platform, such as a platform-specific API. A public key credential bound to a platform authenticator is called aplatform credential.

"cross-platform"

The authenticator is not a part of the device WebAuthn is running on (termed aroaming authenticator as it can roam between different devices), therefore WebAuthn will communicate with it using a cross-platform transport protocol such as Bluetooth or NFC. A public key credential bound to a roaming authenticator is called aroaming credential.

If omitted, any type of authenticator, either platform or cross-platform, can be selected for the credential creation operation.

requireResidentKeyOptional

A boolean. If set totrue, it indicates that the relying party wants to create adiscoverable credential.

This option is retained only for backwards compatibility: callers should use theresidentKey option instead. IfresidentKey is given and is supported, thenrequireResidentKey is ignored. TherequireResidentKey option should be set totrue if and only ifresidentKey is set to"required".

Defaults tofalse.

residentKeyOptional

A string that specifies the extent to which the relying party wants to create adiscoverable credential.Possible values are:

"discouraged"

The relying party prefers creation of a server-side credential, but will accept a client-side discoverable credential.

"preferred"

The relying party strongly prefers creation of a discoverable credential, but will accept a non-discoverable credential. The user agent should guide the user through setting up user verification, if needed, to create a discoverable credential. This takes precedence over theuserVerification setting.

"required"

The relying party requires a discoverable credential. If one cannot be created, aNotAllowedErrorDOMException is thrown. See thecreate() exceptions list for more details.

If omitted,residentKey defaults to"required" ifrequireResidentKey istrue, otherwise the default value is"discouraged".

userVerificationOptional

A string that specifies the relying party's requirements for user verification for thecreate() operation. Possible values are:

"discouraged"

The relying party prefers no user verification for thecreate() operation, in the interests of minimizing disruption to the user experience.

"preferred"

The relying party prefers user verification for thecreate() operation, but it will not fail if user verification cannot be performed.

"required"

The relying party requires user verification for thecreate() operation — if user verification cannot be performed, an error is thrown.

If omitted,userVerification defaults to"preferred".

challenge

AnArrayBuffer,TypedArray, orDataView provided by the relying party's server and used as acryptographic challenge. This value will be signed by the authenticator and the signature will be sent back as part ofAuthenticatorAttestationResponse.attestationObject.

excludeCredentialsOptional

AnArray of objects describing existing credentials that are already mapped to this user account (as identified byuser.id). This is provided by the relying party, and checked by the user agent to avoid creating a new public key credential on an authenticator that already has a credential mapped to the specified user account. Each item should be of the form:

id

AnArrayBuffer,TypedArray, orDataView representing the existing credential ID.

transportsOptional

AnArray of strings representing allowed transports. Possible transports are:"ble","hybrid","internal","nfc", and"usb" (seegetTransports() for more details).

type

A string defining the type of public key credential to create. This can currently take a single value,"public-key", but more values may be added in the future.

If thecreate() call is attempting to create a duplicate public key credential on an authenticator, the user agent will guide to user to create the credential using a different authenticator, or fail if that is not possible.

IfexcludeCredentials is omitted, it defaults to an empty array.

extensionsOptional

An object containing properties representing the input values for any requested extensions. These extensions are used to specific additional processing by the client or authenticator during the credential creation process. Examples include specifying whether a returned credential is discoverable, or whether the relying party will be able to store large blob data associated with a credential.

Extensions are optional and different browsers may recognize different extensions. Processing extensions is always optional for the client: if a browser does not recognize a given extension, it will just ignore it. For information on using extensions, and which ones are supported by which browsers, seeWeb Authentication extensions.

hintsOptionalExperimental

An array of strings providing hints as to what UI the browser should provide for the user to create a public key credential.

The strings can be any of the following:

"security-key"

The UI should recommend using a separate physical security key (such as a YubiKey) to create the credential.

"client-device"

The UI should recommend using an authenticator available on the same device they are using to access the RP client to create the credential. It is analogous to theauthenticatorAttachmentplatform value.

"hybrid"

The UI should recommend using a general-purpose authenticator, such as a smartphone-based authenticator app, to create the credential. This favors using a cross-device approach to handling authentication, relying on a combination of laptop and smartphone, for example.

TheauthenticatorAttachmentcross-platform value is essentially a combination of thehints optionsecurity-key andhybrid values — if a device doesn't have bluetooth and an RP specifiesattachment: "cross-platform", the resulting UI will likely be similar to thehints: "security-key" UI.

When multiple strings are included in the array, their order denotes the order of preference, from high to low. Supporting browsers that respect the hints should use the first one that they understand.

Thehints option provides a more flexible way to specify UI preferences for creating a credential than theauthenticatorAttachment option, which completely hides the non-chosen option.hints also allow indicating a preference for either security keys or hybrid, which is not possible to do withauthenticatorAttachment.

Specifiedhints may contradict hints provided in theauthenticatorAttachment option. When the providedhints contradict this option, thehints take precedence.hints may also be ignored by the browser under specific circumstances, for example if a hinted authenticator type is not usable on the user's device.

For some specific code and UI examples, seeIntroducing hints, Related Origin Requests and JSON serialization for WebAuthn in Chrome.

pubKeyCredParams

AnArray of objects which specify the key types and signature algorithms the Relying Party supports, ordered from most preferred to least preferred. The client and authenticator will make a best-effort to create a credential of the most preferred type possible. These objects will contain the following properties:

alg

A number that is equal to aCOSE Algorithm Identifier, representing the cryptographic algorithm to use for this credential type. It is recommended that relying parties that wish to support a wide range of authenticators should include at least the following values in the provided choices:

• -8: EdDSA
• -7: ES256
• -257: RS256

type

A string defining the type of public key credential to create. This can currently take a single value,"public-key", but more values may be added in the future.

If none of the listed credential types can be created, thecreate() operation fails.

rp

An object describing the relying party that requested the credential creation. It can contain the following properties:

idOptional

A string representing the ID of the relying party. A public key credential can only be used for authentication with the same relying party (as identified by thepublicKey.rpId in anavigator.credentials.get() call) it was registered with — the IDs need to match.

Theid cannot include a port or scheme like a standard origin, but the domain scheme must behttps scheme. Theid needs to equal the origin's effective domain, or a domain suffix thereof. So for example if the relying party's origin ishttps://login.example.com:1337, the followingids are valid:

• login.example.com
• example.com

But not:

• m.login.example.com
• com

If omitted,id defaults to the document origin — which would belogin.example.com in the above example.

name

A string representing the name of the relying party (e.g.,"Facebook"). This is the name the user will be presented with when creating or validating a WebAuthn operation.

timeoutOptional

A numerical hint, in milliseconds, which indicates the time the calling web app is willing to wait for the creation operation to complete. This hint may be overridden by the browser.

user

An object describing the user account for which the credential is generated. It can contain the following properties:

displayName

A string providing a human-friendly user display name (example:"Maria Sanchez"), which will have been set by user during initial registration with the relying party.

id

AnArrayBuffer,TypedArray, orDataView representing a unique ID for the user account. This value has a maximum length of 64 bytes, and is not intended to be displayed to the user.

name

A string providing a human-friendly identifier for the user's account, to help distinguish between different accounts with similardisplayNames. This could be an email address (such as"elaina.sanchez@example.com"), phone number (for example"+12345678901"), or some other kind of user account identifier (for example"ElainaSanchez667").

Examples

Creating a public key credential

This example creates aPublicKeyCredentialCreationOptions, specifying only the required properties, and using defaults for the rest.

It then passes the object intonavigator.credentials.create(), to create a new public key credential.

const publicKey = {  challenge: challengeFromServer,  rp: { id: "acme.com", name: "ACME Corporation" },  user: {    id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]),    name: "jamiedoe",    displayName: "Jamie Doe",  },  pubKeyCredParams: [{ type: "public-key", alg: -7 }],};const publicKeyCredential = await navigator.credentials.create({ publicKey });

A successfulcreate() call returns a promise that resolves with aPublicKeyCredential object instance, representing a public key credential that can later be used to authenticate a user via a WebAuthnget() call. ItsPublicKeyCredential.response property contains anAuthenticatorAttestationResponse object providing access to several useful pieces of information including the authenticator data, public key, transport mechanisms, and more.

navigator.credentials.create({ publicKey }).then((publicKeyCredential) => {  const response = publicKeyCredential.response;  // Access attestationObject ArrayBuffer  const attestationObj = response.attestationObject;  // Access client JSON  const clientJSON = response.clientDataJSON;  // Return authenticator data ArrayBuffer  const authenticatorData = response.getAuthenticatorData();  // Return public key ArrayBuffer  const pk = response.getPublicKey();  // Return public key algorithm identifier  const pkAlgo = response.getPublicKeyAlgorithm();  // Return permissible transports array  const transports = response.getTransports();});

Some of this data will need to be stored on the server for future authentication operations against this credential — for example the public key, the algorithm used, and the permissible transports.

SeeCreating a key pair and registering a user for more information about how the overall flow works.

Specifications

Browser compatibility