From cbf2e97bb3f8ba69a7e325eb2a3305cbde88fe4b Mon Sep 17 00:00:00 2001
From: wbamberg <will@bootbonnet.ca>
Date: Wed, 1 May 2024 13:06:58 -0700
Subject: [PATCH] Normalize CredentialsContainer.create() method

---
 files/en-us/glossary/authentication/index.md  |  23 ++
 files/en-us/glossary/credential/index.md      |  22 ++
 .../api/credentialscontainer/create/index.md  | 344 ++++--------------
 .../web/api/federatedcredentialinit/index.md  |  55 +++
 .../web/api/passwordcredentialinit/index.md   | 163 +++++++++
 .../index.md                                  |  14 +-
 .../index.md                                  | 251 +++++++++++++
 7 files changed, 593 insertions(+), 279 deletions(-)
 create mode 100644 files/en-us/glossary/authentication/index.md
 create mode 100644 files/en-us/glossary/credential/index.md
 create mode 100644 files/en-us/web/api/federatedcredentialinit/index.md
 create mode 100644 files/en-us/web/api/passwordcredentialinit/index.md
 create mode 100644 files/en-us/web/api/publickeycredentialcreationoptions/index.md

diff --git a/files/en-us/glossary/authentication/index.md b/files/en-us/glossary/authentication/index.md
new file mode 100644
index 000000000000000..73b1c50874d67fe
--- /dev/null
+++ b/files/en-us/glossary/authentication/index.md
@@ -0,0 +1,23 @@
+---
+title: Authentication
+slug: Glossary/Authentication
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+**Authentication** is in general the process of proving that some fact is genuine. More specifically, in web security, it is the process of verifying the claimed identity of some entity, such as a user. This then makes it possible to decide whether to grant the user the access that they are requesting, such as being signed into a particular account.
+
+Authentication is typically performed by having a user present a user identifier along with a {{glossary("credential")}}, such as a password, a one-time SMS code, or an assertion signed with a private key. The system then checks the binding between the user identifier and the credential, so it can decide whether or not to authenticate the user.
+
+Types of authentication information, also called _authentication factors_, are commonly presented in three categories:
+
+- Something the user knows, such as a password.
+- Something the user has, such as a phone.
+- Something the user is, such as a thumbprint.
+
+Multi-factor authentication (MFA) systems require the user to provide more than one factor: for example, a password combined with a one-time code sent to the user's phone.
+
+## See also
+
+- {{rfc("4949", "Internet Security Glossary")}}
diff --git a/files/en-us/glossary/credential/index.md b/files/en-us/glossary/credential/index.md
new file mode 100644
index 000000000000000..e3e8f2416fc3101
--- /dev/null
+++ b/files/en-us/glossary/credential/index.md
@@ -0,0 +1,22 @@
+---
+title: Credential
+slug: Glossary/Credential
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+A **credential** is an object which enables a system to make an {{glossary("authentication")}} decision: for example, to decide whether to sign a user into an account.
+
+In web security, types of credential include:
+
+- a password
+- biometric data
+- a token entered from a one-time SMS code
+- the key used to make authentication assertions in a public-key system such as [Web Authentication](/en-US/docs/Web/API/Web_Authentication_API)
+
+The [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) enables develepers to create, store, and retrieve various types of credential.
+
+## See also
+
+- {{rfc("4949", "Internet Security Glossary")}}
diff --git a/files/en-us/web/api/credentialscontainer/create/index.md b/files/en-us/web/api/credentialscontainer/create/index.md
index b4beb66a995c5cc..4477a8237b7fa47 100644
--- a/files/en-us/web/api/credentialscontainer/create/index.md
+++ b/files/en-us/web/api/credentialscontainer/create/index.md
@@ -8,18 +8,19 @@ browser-compat: api.CredentialsContainer.create
 
 {{APIRef("Credential Management API")}}{{SecureContext_Header}}
 
-The **`create()`** method of the {{domxref("CredentialsContainer")}} interface returns a {{jsxref("Promise")}} that resolves with a new credential instance based on the provided options, the information from which can then be stored and later used to authenticate users via {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}}.
+The **`create()`** method of the {{domxref("CredentialsContainer")}} interface creates a new {{glossary("credential")}}, which can then be stored and later used to authenticate users via {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}}.
 
-This is used by multiple different credential-related APIs with significantly different purposes:
+This method supports three different types of credential:
 
-- The [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) uses `create()` to create basic federated credentials or username/password credentials.
-- The [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) uses `create()` to create public key credentials (based on asymmetric cryptography).
+- A password credential, which enables a user to sign in using a password.
+- A federated credential, which enables a user to sign in using a federated identity provider.
+- A public key credential, which enables a user to sign in with an authenticator such as a biometric reader built into the platform or a removable hardware token.
 
-The below reference page starts with a syntax section that explains the general method call structure and parameters that apply to all the different APIs. After that, it is split into separate sections providing parameters, return values, and examples specific to each API.
+Note that the [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) supersedes the federated credential type.
 
 > **Note:** This method is restricted to top-level {{glossary("browsing context", "browsing contexts")}} (i.e., a document running directly inside a browser tab, and not embedded inside another document). Calls to it from within an `<iframe>` element will resolve without effect.
 
-## General syntax
+## Syntax
 
 ```js-nolint
 create()
@@ -38,307 +39,106 @@ create(options)
     Each of the following properties represents a _credential type_ being created. Only one of them can be specified:
 
     - `federated` {{optional_inline}}
-      - : An object containing requirements for creating a federated identify provider credential. Bear in mind that the [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) supersedes this credential type. See the [Credential Management API](#credential_management_api) section below for more details.
+      - : A {{domxref("FederatedCredentialInit")}} object containing requirements for creating a federated identify provider credential.
     - `password` {{optional_inline}}
-      - : An object containing requirements for creating a password credential. See the [Credential Management API](#credential_management_api) section below for more details.
+      - : A {{domxref("PasswordCredentialInit")}} object containing requirements for creating a password credential.
     - `publicKey` {{optional_inline}}
-      - : An object containing requirements for creating a public key credential. Causes the `create()` call to request that the user agent creates new credentials via an authenticator — either for registering a new account or for associating a new asymmetric key pair with an existing account. See the [Web Authentication API](#web_authentication_api) section below for more details.
 
-## Credential Management API
+      - : A {{domxref("PublicKeyCredentialCreationOptions")}} object containing requirements for creating a public key credential. Causes the `create()` call to request that the user agent creates new credentials via an authenticator — either for registering a new account or for associating a new asymmetric key pair with an existing account.
 
-The [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) lets a website store and retrieve password and federated credentials. These capabilities allow users to sign in without typing passwords, see the federated account they used to sign in to a site, and resume a session without the explicit sign-in flow of an expired session.
-
-### `federated` object structure
-
-`federated` can contain the following properties:
-
-- `iconURL` {{optional_inline}}
-  - : A string representing the URL of an icon or avatar to be associated with the credential.
-- `id`
-  - : A string representing a unique ID for the credential.
-- `name` {{optional_inline}}
-  - : A string representing the credential username.
-- `origin`
-  - : A string representing the credential's origin. {{domxref("FederatedCredential")}} objects are origin-bound, which means that they will only be usable on the specified origin they were intended to be used on.
-- `protocol` {{optional_inline}}
-  - : A string representing the protocol of the credentials' federated identity provider (for example, `"openidconnect"`).
-- `provider`
-  - : A string representing the credentials' federated identity provider (for example `"https://www.facebook.com"` or `"https://accounts.google.com"`).
-
-### `password` object structure
-
-A `password` object can be a reference to an object literal or an {{domxref("HTMLFormElement")}}. In both cases, they need to provide the following data:
-
-- `iconURL` {{optional_inline}}
-  - : A string representing the URL of an icon or avatar to be associated with the credential.
-- `id`
-  - : A string representing a unique ID for the credential.
-- `name` {{optional_inline}}
-  - : A string representing the credential username.
-- `origin`
-  - : A string representing the credential's origin. {{domxref("PasswordCredential")}} objects are origin-bound, which means that they will only be usable on the specified origin they were intended to be used on.
-- `password`
-  - : A string representing the credential password.
-
-In the case of the string literal, the properties are provided as-is. In the case of the {{domxref("HTMLFormElement")}}, the values need to be provided in form input fields (this can include {{htmlelement("input")}}, {{htmlelement("select")}}, or {{htmlelement("textarea")}} elements) with the following `name` attribute values:
-
-- `id`: `"username"`
-- `name`: `"name"` or `"nickname"`
-- `iconURL`: `"photo"`
-- `password`: `"new-password"` or `"current-password"`
-
-The exception to this is `origin` — this is set to the origin of the document the {{domxref("HTMLFormElement")}} is contained within.
+        > **Note:** Usage of `create()` with the `publicKey` parameter may be blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server.
 
 ### Return value
 
-A {{jsxref("Promise")}} that resolves with a {{domxref("Credential")}} instance matching the provided parameters:
+A {{jsxref("Promise")}} that resolves one of the following:
 
-- If the created credential type was a `federated` object, the returned instance will be a {{domxref("FederatedCredential")}}.
-- If the created credential type was a `password` object, the returned instance will be a {{domxref("PasswordCredential")}}.
+- A {{domxref("FederatedCredential")}}, if the credential type was a `federated` object.
+- A {{domxref("PasswordCredential")}}, if the created credential type was a `password` object.
+- A {{domxref("PublicKeyCredential")}}, if the created credential type was a `publicKey` object.
 
-If a single credential cannot be successfully created, the Promise will resolve to `null`.
+If no credential object can be created, the promise resolves with `null`.
 
 ### Exceptions
 
 - {{jsxref("TypeError")}}
   - : In the case of a {{domxref("PasswordCredential")}} creation request, `id`, `origin`, or `password` were not provided (empty).
+- `NotAllowedError` {{domxref("DOMException")}}
+  - : Possible causes include:
+    - Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
+    - The function is called cross-origin but the iframe's [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow) attribute does not set an appropriate {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} policy.
+    - The function is called cross-origin and the `<iframe>` does not have {{glossary("transient activation")}}.
 
-### Examples
+## Examples
+
+### Creating a password credential
+
+This example creates a password credential from a {{domxref("PasswordCredentialInit")}} object.
 
 ```js
-navigator.credentials
-  .create({
-    password: {
-      id: "ergnjregoith5y9865jhokmfdskl;vmfdl;kfd...",
-      name: "fluffybunny",
-      origin: "example.com",
-      password: "fluffyhaxx0r",
-    },
-  })
-  .then((pwdCred) => {
-    console.log(pwdCred.name);
+const credInit = {
+  id: "1234",
+  name: "Serpentina",
+  origin: "https://example.org",
+  password: "the last visible dog",
+};
+
+const makeCredential = document.querySelector("#make-credential");
+
+makeCredential.addEventListener("click", async () => {
+  const cred = await navigator.credentials.create({
+    password: credInit,
   });
+  console.log(cred.name);
+  // Serpentina
+  console.log(cred.password);
+  // the last visible dog
+});
 ```
 
-## Web Authentication API
-
-The [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) enables strong authentication with public key cryptography, enabling passwordless authentication and/or secure multi-authentication (MFA) without SMS texts. Check out the linked API landing page for more usage information.
-
-> **Note:** Usage of `create()` with the `publicKey` parameter may be blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server.
-
-### `publicKey` object structure
-
-The `publicKey` object can contain the following properties:
-
-- `attestation` {{optional_inline}}
-
-  - : 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 the `attestation` 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.
-
-    If `attestation` is omitted, it will default to `"none"`.
-
-- `attestationFormats` {{optional_inline}}
-
-  - : 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, see [WebAuthn Attestation Statement Format Identifiers](https://www.iana.org/assignments/webauthn/webauthn.xhtml#webauthn-attestation-statement-format-ids).
-
-    If omitted, `attestationFormats` defaults to an empty array.
-
-- `authenticatorSelection` {{optional_inline}}
-
-  - : An object whose properties are criteria used to filter out the potential authenticators for the credential creation operation. This object can contain the properties:
-
-    - `authenticatorAttachment` {{optional_inline}}
-
-      - : 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 a **platform 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 a **platform credential**.
-        - `"cross-platform"`
-
-          - : The authenticator is not a part of the device WebAuthn is running on (termed a **roaming 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 a **roaming credential**.
-
-            If omitted, any type of authenticator, either platform or cross-platform, can be selected for the credential creation operation.
-
-    - `requireResidentKey` {{optional_inline}}
-
-      - : A boolean. If set to `true`, it indicates that a resident key is required (see `residentKey`) This property is deprecated, but still available in some implementations for backwards compatibility with WebAuthn Level 1. The value should be set to `true` if `residentKey` is set to `"required"`.
-
-        If omitted, `requireResidentKey` defaults to `false`.
-
-    - `residentKey` {{optional_inline}}
-
-      - : A string that specifies the extent to which the relying party desires to create a **client-side discoverable credential** (i.e., one that is usable in authentication requests where the relying party does not provide credential IDs — {{domxref("CredentialsContainer.get()", "navigator.credentials.get()")}} is called with an empty `allowCredentials` value). The alternative is a **server-side credential**, where the relying party must provide credential IDs in the `get()` `allowCredentials` value.
-        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 client-side discoverable credential, but will accept a server-side credential. The user agent should guide the user through setting up user verification, if needed, to create a discoverable credential. This takes precedence over the `userVerification` setting.
-        - `"required"`
-          - : The relying party requires a client-side discoverable credential. If one cannot be created, an error is thrown.
-
-        If omitted, `residentKey` defaults to `"required"` if `requireResidentKey` is `true`, otherwise the default value is `"discouraged"`.
-
-    - `userVerification` {{optional_inline}}
-
-      - : A string that specifies the relying party's requirements for user verification for the `create()` operation. Possible values are:
-
-        - `"discouraged"`
-          - : The relying party prefers no user verification for the `create()` operation, in the interests of minimizing disruption to the user experience.
-        - `"preferred"`
-          - : The relying party prefers user verification for the `create()` operation, but it will not fail if user verification cannot be performed.
-        - `"required"`
-          - : The relying party requires user verification for the `create()` operation — if user verification cannot be performed, an error is thrown.
-
-        If omitted, `userVerification` defaults to `"preferred"`.
-
-- `challenge`
-
-  - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} provided by the relying party's server and used as a [cryptographic challenge](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication). This value will be signed by the authenticator and the signature will be sent back as part of {{domxref("AuthenticatorAttestationResponse.attestationObject")}}.
-
-- `excludeCredentials` {{optional_inline}}
+### Creating a federated credential
 
-  - : An {{jsxref("Array")}} of objects describing existing credentials that are already mapped to this user account (as identified by `user.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. for an existing user who already has some. Each item should be of the form:
+This example creates a password credential from a {{domxref("FederatedCredentialInit")}} object.
 
-    - `id`
-
-      - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} representing the existing credential ID.
-
-    - `transports` {{optional_inline}}
-
-      - : An {{jsxref("Array")}} of strings representing allowed transports. Possible transports are: `"ble"`, `"hybrid"`, `"internal"`, `"nfc"`, and `"usb"` (see {{domxref("AuthenticatorAttestationResponse.getTransports", "getTransports()")}} 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 the `create()` 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.
-
-    If `excludeCredentials` is omitted, it defaults to an empty array.
-
-- `extensions` {{optional_inline}}
-
-  - : 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, see [Web Authentication extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions).
-
-- `pubKeyCredParams`
-
-  - : An {{jsxref("Array")}} 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 a [COSE Algorithm Identifier](https://www.iana.org/assignments/cose/cose.xhtml#algorithms), 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`: Ed25519
-        - `-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, the `create()` operation fails.
-
-- `rp`
-
-  - : An object describing the relying party that requested the credential creation. It can contain the following properties:
-
-    - `id` {{optional_inline}}
-
-      - : 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 the `publicKey.rpId` in a {{domxref("CredentialsContainer.get()", "navigator.credentials.get()")}} call) it was registered with — the IDs need to match.
-
-        The `id` cannot include a port or scheme like a standard origin, but the domain scheme must be `https` scheme. The `id` needs to equal the origin's effective domain, or a domain suffix thereof. So for example if the relying party's origin is `https://login.example.com:1337`, the following `id`s are valid:
-
-        - `login.example.com`
-        - `example.com`
-
-        But not:
-
-        - `m.login.example.com`
-        - `com`
-
-        If omitted, `id` defaults to the document origin — which would be `login.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.
-
-- `timeout` {{optional_inline}}
-
-  - : 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: `"John Doe"`), which will have been set by user during initial registration with the relying party.
-
-    - `id`
-
-      - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} 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 similar `displayName`s. This could be an email address (such as `"john.doe@example.com"`), phone number (for example `"+12345678901"`), or some other kind of user account identifier (for example `"johndoe667"`).
-
-- `hints` {{optional_inline}}
-
-  - : An array of strings providing hints as to what authentication UI the user-agent should provide for the user.
-
-    The values can be any of the following:
-
-    - `"security-key"`
-      - : Authentication requires a separate dedicated physical device to provide the key.
-    - `"client-device"`
-      - : The user authenticates using their own device, such as a phone.
-    - `"hybrid"`
-      - : Authentication relies on a combination of authorization/authentication methods, potentially relying on both user and server-based mechanisms.
-
-### Return value
-
-A {{jsxref("Promise")}} that resolves with an {{domxref("PublicKeyCredential")}} instance matching the provided parameters. If no credential object can be created, the promise resolves with `null`.
-
-### Exceptions
-
-- `NotAllowedError` {{domxref("DOMException")}}
-  - : Possible causes include:
-    - Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
-    - The function is called cross-origin but the iframe's [`allow`](/en-US/docs/Web/HTML/Element/iframe#allow) attribute does not set an appropriate {{HTTPHeader("Permissions-Policy/publickey-credentials-create","publickey-credentials-create")}} policy.
-    - The function is called cross-origin and the `<iframe>` does not have {{glossary("transient activation")}}.
+```js
+const credInit = {
+  id: "1234",
+  name: "Serpentina",
+  origin: "https://example.org",
+  protocol: "openidconnect",
+  provider: "https://provider.example.org",
+};
+
+const makeCredential = document.querySelector("#make-credential");
+
+makeCredential.addEventListener("click", async () => {
+  const cred = await navigator.credentials.create({
+    federated: credInit,
+  });
+  console.log(cred.name);
+  console.log(cred.provider);
+});
+```
 
-## Examples
+### Creating a public key credential
 
-The following snippet shows a typical `create()` call with the WebAuthn `publicKey` option:
+This example creates a public key credential from a from a {{domxref("PublicKeyCredentialCreationOptions")}} object.
 
 ```js
 const publicKey = {
-  challenge: new Uint8Array([117, 61, 252, 231, 191, 241, ...]),
+  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"
+    displayName: "Jamie Doe",
   },
-  pubKeyCredParams: [ {type: "public-key", alg: -7} ]
-}
+  pubKeyCredParams: [{ type: "public-key", alg: -7 }],
+};
 
-navigator.credentials.create({ publicKey })
+const publicKeyCredential = await navigator.credentials.create({ publicKey });
 ```
 
-A successful `create()` call returns a promise that resolves with a {{domxref("PublicKeyCredential")}} object instance, representing a public key credential that can later be used to authenticate a user via a WebAuthn {{domxref("CredentialsContainer.get()", "get()")}} call. Its {{domxref("PublicKeyCredential.response")}} property contains an {{domxref("AuthenticatorAttestationResponse")}} object providing access to several useful pieces of information including the authenticator data, public key, transport mechanisms, and more.
+The `create()` call, if successful, returns a promise that resolves with a {{domxref("PublicKeyCredential")}} object instance, representing a public key credential that can later be used to authenticate a user via a WebAuthn {{domxref("CredentialsContainer.get()", "get()")}} call. Its {{domxref("PublicKeyCredential.response")}} property contains an {{domxref("AuthenticatorAttestationResponse")}} object providing access to several useful pieces of information including the authenticator data, public key, transport mechanisms, and more.
 
 ```js
 navigator.credentials.create({ publicKey }).then((publicKeyCredential) => {
diff --git a/files/en-us/web/api/federatedcredentialinit/index.md b/files/en-us/web/api/federatedcredentialinit/index.md
new file mode 100644
index 000000000000000..eadf547127c7b68
--- /dev/null
+++ b/files/en-us/web/api/federatedcredentialinit/index.md
@@ -0,0 +1,55 @@
+---
+title: FederatedCredentialInit
+slug: Web/API/FederatedCredentialInit
+page-type: web-api-interface
+spec-urls: https://w3c.github.io/webappsec-credential-management/#dom-federatedcredential-federatedcredential
+---
+
+{{APIRef("Credential Management API")}}{{SecureContext_Header}}
+
+The **`FederatedCredentialInit`** dictionary represents the object passed to {{domxref("CredentialsContainer.create()")}} as the value of the `federated` option: that is, when using `create()` to create a federated identify provider credential.
+
+Note that the [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API) supersedes this credential type.
+
+## Instance properties
+
+- `iconURL` {{optional_inline}}
+  - : A string representing the URL of an icon or avatar to be associated with the credential.
+- `id`
+  - : A string representing a unique ID for the credential.
+- `name` {{optional_inline}}
+  - : A string representing the credential username.
+- `origin`
+  - : A string representing the credential's origin. {{domxref("FederatedCredential")}} objects are origin-bound, which means that they will only be usable on the specified origin they were intended to be used on.
+- `protocol` {{optional_inline}}
+  - : A string representing the protocol of the credentials' federated identity provider (for example, `"openidconnect"`).
+- `provider`
+  - : A string representing the credentials' federated identity provider (for example `"https://www.facebook.com"` or `"https://accounts.google.com"`).
+
+## Examples
+
+### Creating a federated identity credential
+
+```js
+const credInit = {
+  id: "1234",
+  name: "Serpentina",
+  origin: "https://example.org",
+  protocol: "openidconnect",
+  provider: "https://provider.example.org",
+};
+
+const makeCredential = document.querySelector("#make-credential");
+
+makeCredential.addEventListener("click", async () => {
+  const cred = await navigator.credentials.create({
+    federated: credInit,
+  });
+  console.log(cred.name);
+  console.log(cred.provider);
+});
+```
+
+## Specifications
+
+{{Specifications}}
diff --git a/files/en-us/web/api/passwordcredentialinit/index.md b/files/en-us/web/api/passwordcredentialinit/index.md
new file mode 100644
index 000000000000000..8e2c71fa638aaab
--- /dev/null
+++ b/files/en-us/web/api/passwordcredentialinit/index.md
@@ -0,0 +1,163 @@
+---
+title: PasswordCredentialInit
+slug: Web/API/PasswordCredentialInit
+page-type: web-api-interface
+spec-urls: https://w3c.github.io/webappsec-credential-management/#typedefdef-passwordcredentialinit
+---
+
+{{APIRef("Credential Management API")}}{{SecureContext_Header}}
+
+The **`PasswordCredentialInit`** dictionary represents the object passed to {{domxref("CredentialsContainer.create()")}} as the value of the `password` option: that is, when using `create()` to create a password credential.
+
+## Initialization from a form
+
+Instead of passing this dictionary directly, a website can pass an {{domxref("HTMLFormElement")}}, and the implementation of `create()` will populate the credential's data from the values of the form's submittable elements, based on the value of the element's [`autocomplete`](/en-US/docs/Web/HTML/Attributes/autocomplete) attribute.
+
+| `autocomplete` value                     | Credential property targeted |
+| ---------------------------------------- | ---------------------------- |
+| `"username"`                             | `id`                         |
+| `"name"` or `"nickname"`                 | `name`                       |
+| `"new-password"` or `"current-password"` | `password`                   |
+| `"photo"`                                | `iconURL`                    |
+
+If the form contains both `"new-password"` and `"current-password"` elements, the value for `"new-password"` will be used.
+
+The `origin` property is set to the origin of the document the {{domxref("HTMLFormElement")}} is contained within.
+
+## Instance properties
+
+- `iconURL` {{optional_inline}}
+  - : A string representing the URL of an icon or avatar to be associated with the credential.
+- `id`
+  - : A string representing a unique ID for the credential.
+- `name` {{optional_inline}}
+  - : A string representing the credential username.
+- `origin`
+  - : A string representing the credential's origin. {{domxref("PasswordCredential")}} objects are origin-bound, which means that they will only be usable on the specified origin they were intended to be used on.
+- `password`
+  - : A string representing the credential password.
+
+## Examples
+
+### Creating a password credential from an object literal
+
+This example constructs an object literal to initialize a password credential.
+
+```js
+const credInit = {
+  id: "1234",
+  name: "Serpentina",
+  origin: "https://example.org",
+  password: "the last visible dog",
+};
+
+const makeCredential = document.querySelector("#make-credential");
+
+makeCredential.addEventListener("click", async () => {
+  const cred = await navigator.credentials.create({
+    password: credInit,
+  });
+  console.log(cred.name);
+  // Serpentina
+  console.log(cred.password);
+  // the last visible dog
+});
+```
+
+### Creating a password credential from a form
+
+This example uses a form to initialize a password credential.
+
+#### HTML
+
+The HTML declares a {{HTMLElement("form")}} containing three submittable elements, representing the user ID, user's display name, and password.
+
+```html
+<form>
+  <div>
+    <label for="userid">Enter your user ID: </label>
+    <input type="text" name="userid" id="userid" autocomplete="username" />
+  </div>
+  <div>
+    <label for="username">Enter your username: </label>
+    <input type="text" name="username" id="username" autocomplete="name" />
+  </div>
+  <div>
+    <label for="password">Enter your password: </label>
+    <input
+      type="password"
+      name="password"
+      id="password"
+      autocomplete="new-password" />
+  </div>
+</form>
+
+<button id="make-credential">Make credential</button>
+
+<pre id="log"></pre>
+```
+
+```css hidden
+form {
+  display: table;
+}
+
+div {
+  display: table-row;
+}
+
+label,
+input {
+  display: table-cell;
+  margin-bottom: 10px;
+}
+
+label {
+  padding-right: 10px;
+}
+
+#log {
+  height: 60px;
+  padding: 0.5rem;
+  border: 1px solid black;
+}
+```
+
+#### JavaScript
+
+The JavaScript passes the form into `create()`, and logs some of the values of the resulting credential.
+
+The promise returned by `create()` will reject if the form does not contain values for the mandatory credential properties.
+
+```js
+const makeCredential = document.querySelector("#make-credential");
+const formCreds = document.querySelector("form");
+
+makeCredential.addEventListener("click", async () => {
+  try {
+    const credential = await navigator.credentials.create({
+      password: formCreds,
+    });
+    log(
+      `New credential:\nname: ${credential.name}, password: ${credential.password}`,
+    );
+  } catch (e) {
+    if (e.name === "TypeError") {
+      log("Error creating credential\nMake sure you filled in all the fields");
+    }
+  }
+});
+
+const logElement = document.querySelector("#log");
+function log(text) {
+  logElement.innerText = text;
+}
+```
+
+#### Result
+
+{{EmbedLiveSample("Creating a password credential from a form", "", "260")}}
+
+## Specifications
+
+{{Specifications}}
diff --git a/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md b/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md
index 6ca3ef1891816ee..874ff34d9a7fa4c 100644
--- a/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md
+++ b/files/en-us/web/api/publickeycredential/parsecreationoptionsfromjson_static/index.md
@@ -10,7 +10,7 @@ browser-compat: api.PublicKeyCredential.parseCreationOptionsFromJSON_static
 
 {{APIRef("Web Authentication API")}} {{SeeCompatTable}}{{securecontext_header}}
 
-The **`parseCreationOptionsFromJSON()`** static method of the {{domxref("PublicKeyCredential")}} interface converts a {{glossary("JSON type representation")}} into its corresponding [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+The **`parseCreationOptionsFromJSON()`** static method of the {{domxref("PublicKeyCredential")}} interface creates a {{domxref("PublicKeyCredentialCreationOptions")}} object from a JSON representation of its properties.
 
 The method is a convenience function for converting credential options information provided by a relying party server to the form that a web app can use to [create a credential](/en-US/docs/Web/API/Web_Authentication_API#creating_a_key_pair_and_registering_a_user).
 
@@ -24,25 +24,25 @@ PublicKeyCredential.parseCreationOptionsFromJSON(options)
 
 - `options`
 
-  - : An object with the same structure as the Web Authentication API [`publicKey` create credentials options object](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure), but with [base64url](/en-US/docs/Glossary/Base64)-encoded strings used in place of buffer properties.
+  - : An object with the same structure as a {{domxref("PublicKeyCredentialCreationOptions")}}, but with [base64url](/en-US/docs/Glossary/Base64)-encoded strings used in place of buffer properties.
 
 ### Return value
 
-An object with the Web Authentication API [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+A {{domxref("PublicKeyCredentialCreationOptions")}} object.
 
 ### Exceptions
 
 - `EncodingError` {{domxref("DOMException")}}
-  - : Thrown if any part of the `options` object cannot be converted into the [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+  - : Thrown the `options` object cannot be converted into a {{domxref("PublicKeyCredentialCreationOptions")}} object.
 
 ## Description
 
 The Web Authentication process for [creating a key pair and registering a user](/en-US/docs/Web/API/Web_Authentication_API#creating_a_key_pair_and_registering_a_user) involves a relying party server sending the web app information needed to create a credential, including details about the user identity, the relying party, and a "challenge".
-The web app passes this information to an authenticator to create the credential, by calling [`navigator.credentials.create()`](/en-US/docs/Web/API/CredentialsContainer/create) with an argument that contains the server-supplied data in the [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure).
+The web app passes this information to an authenticator to create the credential, by calling [`navigator.credentials.create()`](/en-US/docs/Web/API/CredentialsContainer/create) with a {{domxref("PublicKeyCredentialCreationOptions")}} object as an argument.
 
 The specification does not define how the information needed for creating a credential is sent.
-A convenient approach is for the server to encapsulate the information in a {{glossary("JSON type representation")}} of the [`publicKey` create credentials options object](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure) that mirrors its structure but encodes buffer properties such as the `challenge` and `user.id` as [base64url](/en-US/docs/Glossary/Base64) strings.
-This object can be serialized to a [JSON](/en-US/docs/Glossary/JSON) string, sent to the web app and deserialized, and then converted to the [`publicKey` create credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/create#publickey_object_structure) using **`parseCreationOptionsFromJSON()`**.
+A convenient approach is for the server to encapsulate the information in a {{glossary("JSON type representation")}} of the {{domxref("PublicKeyCredentialCreationOptions")}} object that mirrors its structure but encodes buffer properties such as the `challenge` and `user.id` as [base64url](/en-US/docs/Glossary/Base64) strings.
+This object can be serialized to a [JSON](/en-US/docs/Glossary/JSON) string, sent to the web app and deserialized, and then converted to a {{domxref("PublicKeyCredentialCreationOptions")}} object using **`parseCreationOptionsFromJSON()`**.
 
 ## Examples
 
diff --git a/files/en-us/web/api/publickeycredentialcreationoptions/index.md b/files/en-us/web/api/publickeycredentialcreationoptions/index.md
new file mode 100644
index 000000000000000..870448f56b5139a
--- /dev/null
+++ b/files/en-us/web/api/publickeycredentialcreationoptions/index.md
@@ -0,0 +1,251 @@
+---
+title: PublicKeyCredentialCreationOptions
+slug: Web/API/PublicKeyCredentialCreationOptions
+page-type: web-api-interface
+browser-compat: api.CredentialsContainer.create.publicKey_option
+spec-urls: https://w3c.github.io/webauthn/#dictionary-makecredentialoptions
+---
+
+{{APIRef("Web Authentication API")}}{{securecontext_header}}
+
+The **`PublicKeyCredentialCreationOptions`** dictionary represents the object passed to {{domxref("CredentialsContainer.create()")}} as the value of the `publicKey` option: that is, when using `create()` to create a public key credential using the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API).
+
+## Instance properties
+
+- `attestation` {{optional_inline}}
+
+  - : 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 the `attestation` 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.
+
+    If `attestation` is omitted, it will default to `"none"`.
+
+- `attestationFormats` {{optional_inline}}
+
+  - : 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, see [WebAuthn Attestation Statement Format Identifiers](https://www.iana.org/assignments/webauthn/webauthn.xhtml#webauthn-attestation-statement-format-ids).
+
+    If omitted, `attestationFormats` defaults to an empty array.
+
+- `authenticatorSelection` {{optional_inline}}
+
+  - : An object whose properties are criteria used to filter out the potential authenticators for the credential creation operation. This object can contain the properties:
+
+    - `authenticatorAttachment` {{optional_inline}}
+
+      - : 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 a **platform 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 a **platform credential**.
+        - `"cross-platform"`
+
+          - : The authenticator is not a part of the device WebAuthn is running on (termed a **roaming 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 a **roaming credential**.
+
+            If omitted, any type of authenticator, either platform or cross-platform, can be selected for the credential creation operation.
+
+    - `requireResidentKey` {{optional_inline}}
+
+      - : A boolean. If set to `true`, it indicates that a resident key is required (see `residentKey`) This property is deprecated, but still available in some implementations for backwards compatibility with WebAuthn Level 1. The value should be set to `true` if `residentKey` is set to `"required"`.
+
+        If omitted, `requireResidentKey` defaults to `false`.
+
+    - `residentKey` {{optional_inline}}
+
+      - : A string that specifies the extent to which the relying party desires to create a **client-side discoverable credential** (i.e., one that is usable in authentication requests where the relying party does not provide credential IDs — {{domxref("CredentialsContainer.get()", "navigator.credentials.get()")}} is called with an empty `allowCredentials` value). The alternative is a **server-side credential**, where the relying party must provide credential IDs in the `get()` `allowCredentials` value.
+        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 client-side discoverable credential, but will accept a server-side credential. The user agent should guide the user through setting up user verification, if needed, to create a discoverable credential. This takes precedence over the `userVerification` setting.
+        - `"required"`
+          - : The relying party requires a client-side discoverable credential. If one cannot be created, an error is thrown.
+
+        If omitted, `residentKey` defaults to `"required"` if `requireResidentKey` is `true`, otherwise the default value is `"discouraged"`.
+
+    - `userVerification` {{optional_inline}}
+
+      - : A string that specifies the relying party's requirements for user verification for the `create()` operation. Possible values are:
+
+        - `"discouraged"`
+          - : The relying party prefers no user verification for the `create()` operation, in the interests of minimizing disruption to the user experience.
+        - `"preferred"`
+          - : The relying party prefers user verification for the `create()` operation, but it will not fail if user verification cannot be performed.
+        - `"required"`
+          - : The relying party requires user verification for the `create()` operation — if user verification cannot be performed, an error is thrown.
+
+        If omitted, `userVerification` defaults to `"preferred"`.
+
+- `challenge`
+
+  - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} provided by the relying party's server and used as a [cryptographic challenge](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication). This value will be signed by the authenticator and the signature will be sent back as part of {{domxref("AuthenticatorAttestationResponse.attestationObject")}}.
+
+- `excludeCredentials` {{optional_inline}}
+
+  - : An {{jsxref("Array")}} of objects describing existing credentials that are already mapped to this user account (as identified by `user.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. for an existing user who already has some. Each item should be of the form:
+
+    - `id`
+
+      - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} representing the existing credential ID.
+
+    - `transports` {{optional_inline}}
+
+      - : An {{jsxref("Array")}} of strings representing allowed transports. Possible transports are: `"ble"`, `"hybrid"`, `"internal"`, `"nfc"`, and `"usb"` (see {{domxref("AuthenticatorAttestationResponse.getTransports", "getTransports()")}} 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 the `create()` 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.
+
+    If `excludeCredentials` is omitted, it defaults to an empty array.
+
+- `extensions` {{optional_inline}}
+
+  - : 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, see [Web Authentication extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions).
+
+- `pubKeyCredParams`
+
+  - : An {{jsxref("Array")}} 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 a [COSE Algorithm Identifier](https://www.iana.org/assignments/cose/cose.xhtml#algorithms), 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`: Ed25519
+        - `-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, the `create()` operation fails.
+
+- `rp`
+
+  - : An object describing the relying party that requested the credential creation. It can contain the following properties:
+
+    - `id` {{optional_inline}}
+
+      - : 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 the `publicKey.rpId` in a {{domxref("CredentialsContainer.get()", "navigator.credentials.get()")}} call) it was registered with — the IDs need to match.
+
+        The `id` cannot include a port or scheme like a standard origin, but the domain scheme must be `https` scheme. The `id` needs to equal the origin's effective domain, or a domain suffix thereof. So for example if the relying party's origin is `https://login.example.com:1337`, the following `id`s are valid:
+
+        - `login.example.com`
+        - `example.com`
+
+        But not:
+
+        - `m.login.example.com`
+        - `com`
+
+        If omitted, `id` defaults to the document origin — which would be `login.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.
+
+- `timeout` {{optional_inline}}
+
+  - : 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: `"John Doe"`), which will have been set by user during initial registration with the relying party.
+
+    - `id`
+
+      - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} 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 similar `displayName`s. This could be an email address (such as `"john.doe@example.com"`), phone number (for example `"+12345678901"`), or some other kind of user account identifier (for example `"johndoe667"`).
+
+- `hints` {{optional_inline}}
+
+  - : An array of strings providing hints as to what authentication UI the user-agent should provide for the user.
+
+    The values can be any of the following:
+
+    - `"security-key"`
+      - : Authentication requires a separate dedicated physical device to provide the key.
+    - `"client-device"`
+      - : The user authenticates using their own device, such as a phone.
+    - `"hybrid"`
+      - : Authentication relies on a combination of authorization/authentication methods, potentially relying on both user and server-based mechanisms.
+
+## Examples
+
+### Creating a public key credential
+
+This example creates a `PublicKeyCredentialCreationOptions`, specifying only the required properties, and using defaults for the rest.
+
+It then passes the object into `navigator.credentials.create()`, to create a new public key credential.
+
+```js
+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 successful `create()` call returns a promise that resolves with a {{domxref("PublicKeyCredential")}} object instance, representing a public key credential that can later be used to authenticate a user via a WebAuthn {{domxref("CredentialsContainer.get()", "get()")}} call. Its {{domxref("PublicKeyCredential.response")}} property contains an {{domxref("AuthenticatorAttestationResponse")}} object providing access to several useful pieces of information including the authenticator data, public key, transport mechanisms, and more.
+
+```js
+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.
+
+See [Creating a key pair and registering a user](/en-US/docs/Web/API/Web_Authentication_API#creating_a_key_pair_and_registering_a_user) for more information about how the overall flow works.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}