CredentialsContainer: get() method

options Optional

An object that contains options for the request. It can contain the following properties:

mediation Optional

A string indicating whether the user will be required to login for every visit to a client app. The value can be one of the following:

• "conditional": Discovered credentials are presented to the user in a non-modal dialog box along with an indication of the origin requesting credentials. In practice, this means autofilling available credentials; see Sign in with a passkey through form autofill for more details of how this is used; PublicKeyCredential.isConditionalMediationAvailable() also provides some useful information.

• "optional": If credentials can be handed over for a given operation without user mediation, they will be, enabling automatic reauthentication without user mediation. If user mediation is required, then the user agent will ask the user to authenticate. This value is intended for situations where you have reasonable confidence that a user won't be surprised or confused at seeing a login dialog box — for example on a site that doesn't automatically log users in, when a user has just clicked a "Login/Signup" button.

• "required": The user will always be asked to authenticate, even if prevent silent access (see CredentialsContainer.preventSilentAccess()) is set to false. This value is intended for situations where you want to force user authentication — for example if you want a user to reauthenticate when a sensitive operation is being performed (like confirming a credit card payment), or when switching users.

• "silent": The user will not be asked to authenticate. The user agent will automatically reauthenticate the user and log them in if possible. If consent is required, the promise will fulfill with null. This value is intended for situations where you would want to automatically sign a user in upon visiting a web app if possible, but if not, you don't want to present them with a confusing login dialog box. Instead, you'd want to wait for them to explicitly click a "Login/Signup" button.

The default value is "optional".

Note: In the case of a federated authentication (FedCM API) request, a mediation value of optional or silent may result in attempted auto-reauthentication. Whether this occurred is communicated to the identity provider (IdP) via the is_auto_selected parameter sent to the IdP's id_assertion_endpoint during validation and the relying party (RP) via the IdentityCredential.isAutoSelected property. This is useful for performance evaluation, security requirements (the IdP may wish to reject automatic reauthentication requests and always require user mediation), and general UX (an IdP or RP may wish to present different UX for auto and non-auto login experiences).

signal Optional

An AbortSignal object instance that allows an ongoing get() operation to be aborted. An aborted operation may complete normally (generally if the abort was received after the operation finished) or reject with an AbortError DOMException.

password Optional

This option asks the browser to retrieve a stored password as a PasswordCredential object. It is a boolean value.

identity Optional

This option asks the browser to retrieve a federated identity credential as an IdentityCredential object, using the Federated Credential Management API.

This option's value is an IdentityCredentialRequestOptions object containing details of the specific identity providers that the website wants to use.

federated Optional

This option asks the browser to retrieve a federated identity credential as a FederatedCredential object. This interface is now superseded, and developers should prefer to use the identity option, if it is available.

This option's value is an object with the following properties:

protocols

An array of strings representing the protocols of the requested credentials' federated identity providers (for example, "openidconnect").

providers

An array of strings representing the credentials' federated identity providers (for example "https://www.facebook.com" or "https://accounts.google.com").

otp Optional

This option asks the browser to retrieve a one-time password (OTP) as an OTPCredential object.

This option's value is an array of strings which may only contain the string value "sms".

publicKey Optional

This option asks the browser to retrieve an assertion signed using the Web Authentication API as a PublicKeyCredential.

This option's value is a PublicKeyCredentialRequestOptions object.

A Promise that resolves with one of the following subclasses of Credential:

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

If a single credential cannot be unambiguously obtained, the promise resolves with null.

AbortError DOMException

The request was aborted by a call to the abort() method of the AbortController associated with this method's signal option.

IdentityCredentialError DOMException

When requesting an IdentityCredential, the request to the ID assertion endpoint is unable to validate the authentication, and rejects with an error response containing information about the reason.

NetworkError DOMException

When requesting an IdentityCredential, the identity provider (IdP) did not respond within 60 seconds, the provided credentials were not valid/found, or the browser's login status for the IdP is set to "logged-out" (see Update login status using the Login Status API for more information about FedCM login status). In the latter case, there may be some delay in the rejection to avoid leaking the IdP login status to the RP.

NotAllowedError DOMException

Thrown in one of the following situations:

• Use of this API was blocked by one of the following permissions policies:

  • identity-credentials-get
  • publickey-credentials-get
  • otp-credentials

• The calling origin is an opaque origin.

SecurityError DOMException

The calling domain is not a valid domain.

Relying parties can call get() with the identity option to make a request for users to sign in to the relying party via an identity provider (IdP), using identity federation. A typical request would look like this:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          nonce: "******",
        },
      ],
    },
  });
}

Check out Federated Credential Management (FedCM) API for more details on how this works. This call will start off the sign-in flow described in FedCM sign-in flow.

A similar call including the context and loginHint extensions would look like so:

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      context: "signup",
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          nonce: "******",
          loginHint: "[email protected]",
        },
      ],
    },
  });
}

If the IdP is unable to validate a request to the ID assertion endpoint it will reject the promise returned from CredentialsContainer.get():

async function signIn() {
  try {
    const identityCredential = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: "https://accounts.idp.example/config.json",
            clientId: "********",
            nonce: "******",
          },
        ],
      },
    });
  } catch (e) {
    // Handle the error in some way, for example provide information
    // to help the user succeed in a future sign-in attempt
    console.error(e);
  }
}

The following snippet shows a typical get() call with the WebAuthn publicKey option:

const publicKey = {
  challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]),
  rpId: "acme.com",
  allowCredentials: [{
    type: "public-key",
    id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...])
  }],
  userVerification: "required",
}

navigator.credentials.get({ publicKey })

A successful get() call returns a promise that resolves with a PublicKeyCredential object instance, representing a public key credential previously created via a WebAuthn create() that has now been used to authenticate a user. Its PublicKeyCredential.response property contains an AuthenticatorAssertionResponse object providing access to several useful pieces of information including the authenticator data, signature, and user handle.

navigator.credentials.get({ publicKey }).then((publicKeyCredential) => {
  const response = publicKeyCredential.response;

  // Access authenticator data ArrayBuffer
  const authenticatorData = response.authenticatorData;

  // Access client JSON
  const clientJSON = response.clientDataJSON;

  // Access signature ArrayBuffer
  const signature = response.signature;

  // Access userHandle ArrayBuffer
  const userHandle = response.userHandle;
});

Some of this data will need to be stored on the server — for example the signature to provide proof that authenticator possesses the genuine private key used to create the credential, and the userHandle to link the user with the credential, sign in attempt, and other data.

See Authenticating a user for more information about how the overall flow works.

The code below triggers the browser's permission flow when an SMS message arrives. If permission is granted, then the promise resolves with an OTPCredential object. The contained code value is then set as the value of an <input> form element, which is then submitted.

navigator.credentials
  .get({
    otp: { transport: ["sms"] },
    signal: ac.signal,
  })
  .then((otp) => {
    input.value = otp.code;
    if (form) form.submit();
  })
  .catch((err) => {
    console.error(err);
  });