API in Capabilities
Credential Management API
Published Updated
The Credential Management API lets you retrieve, store, and create a Credential through navigator.credentials, or stop the browser from signing users in silently. The container accepts five credential types: PasswordCredential, PublicKeyCredential (WebAuthn), OTPCredential, IdentityCredential (FedCM), and the superseded FederatedCredential.
CredentialsContainer, get(), and store() ship in Chrome 51, Edge 18, Firefox 60, and Safari 13; create() in Chrome 60; preventSilentAccess() in Chrome 60 (Chrome 51 to 59 called it requireUserMediation()), Edge 18, Firefox 60, and Safari 17, with Safari 13 to 16 exposing a method that rejects every call with NotSupportedError (BCD api.CredentialsContainer). Support for individual credential types is more limited: PasswordCredential exists in Chrome 51 and in no version of Firefox or Safari; get({ otp }) in Chrome 93 (Chrome 84 on Android) and Safari 27; get({ identity }) in Chrome 108 and Safari 27. PublicKeyCredential is the WebAuthn credential type.
Syntax
Section titled “Syntax”navigator.credentials.get()navigator.credentials.get(options)navigator.credentials.store(credential)navigator.credentials.create()navigator.credentials.create(options)navigator.credentials.preventSilentAccess()get() and create() return Promise<Credential?>: a Credential subclass instance, or null when nothing could be obtained or created without more user involvement than mediation allows. store() and preventSilentAccess() return Promise<undefined>. All four are [SecureContext]; the container is undefined on http:// origins other than localhost.
Parameters
Section titled “Parameters”get() takes a CredentialRequestOptions, create() a CredentialCreationOptions, store() a Credential, and preventSilentAccess() nothing. Each credential type adds its own member to the two dictionaries; a request names exactly the types it will accept by including their members.
| Member | Type | Required | Description |
|---|---|---|---|
mediation (get, create) |
"silent", "optional", "conditional", or "required" |
No | Default "optional". "silent" resolves null rather than showing UI; "optional" shows a chooser only when needed; "conditional" surfaces discovered credentials in a non-modal UI (autofill) and does not resolve null promptly; "required" ignores any silent-access opt-in and prompts. For create(), "conditional" lets a recently mediated sign-in create without a modal, else rejects. |
uiMode (get) |
DOMString |
No | "immediate": show a modal chooser if credentials exist, otherwise complete at once with null and no prompt. |
signal (get, create) |
AbortSignal |
No | Aborting rejects with the signal’s reason (AbortError by default, TimeoutError from AbortSignal.timeout()), unless the operation already finished. |
password (get) |
boolean |
No | Default false. true asks for a stored PasswordCredential. |
password (create) |
PasswordCredentialData or HTMLFormElement |
No | PasswordCredentialData has id (required), origin (required), password (required), name, and iconURL; a form is read through its autocomplete tokens. |
federated (get, create) |
FederatedCredentialRequestOptions / FederatedCredentialInit |
No | providers: sequence<USVString> and protocols: sequence<DOMString> for the superseded FederatedCredential. |
publicKey (get, create) |
PublicKeyCredentialRequestOptions / PublicKeyCredentialCreationOptions |
No | WebAuthn; documented under WebAuthn and passkeys. |
otp (get) |
OTPCredentialRequestOptions |
No | transport: ["sms"]; resolves an OTPCredential whose code is the SMS one-time code. |
identity (get) |
IdentityCredentialRequestOptions |
No | providers with configURL, clientId, and optional nonce, loginHint, domainHint; FedCM. |
The credential argument to store() must be a Credential the page obtained from get() or built itself (new PasswordCredential(data) or new PasswordCredential(form)).
Exceptions
Section titled “Exceptions”The algorithms reject in a fixed order. Any rejection the credential type’s own internal methods throw (for example WebAuthn’s NotAllowedError on timeout) is passed through unchanged.
| Exception | Condition |
|---|---|
InvalidStateError |
The document is not fully active (all four methods). Chromium also uses it when another request on the same container is in flight. |
NotSupportedError |
get() with no type member, or two members whose types cannot share a request; create() with more than one type member or without an associated document. Safari 13 to 16 reject every preventSilentAccess() call with it, and Chromium rejects with it when the password store is unavailable. |
SecurityError |
An origin-bound type (PasswordCredential, FederatedCredential) requested, created, or stored from an opaque origin. |
TypeError |
mediation: "conditional" or uiMode: "immediate" with a type that does not support it; create({ password }) whose data or form cannot build a PasswordCredential. |
NotAllowedError |
A request for a type that is already active in this settings object; the type’s Permissions Policy denies the document; PasswordCredential collection or storage from a context that is not same-origin with all its ancestors; create() with mediation: "conditional" without prior consent. |
| The signal’s abort reason | options.signal was already aborted when get() or create() ran, or fired before the operation finished. |
preventSilentAccess() resolves even when the browser stores no credentials; its only specified rejection is InvalidStateError.
Examples
Section titled “Examples”The examples test for PasswordCredential as well as navigator.credentials, because Firefox 60+ and Safari 13+ ship the container without that type: 'credentials' in navigator passes and get({ password: true }) resolves null.
Signing in silently on arrival, with a deadline and a visible fallback
Section titled “Signing in silently on arrival, with a deadline and a visible fallback”mediation: "silent" shows no chooser; it resolves null when consent would be needed, so the page can show its normal sign-in button. AbortSignal.timeout() turns a store that hangs into a TimeoutError.
async function trySilentSignIn() { if (!('credentials' in navigator) || !('PasswordCredential' in window)) { showSignInButton(); return; } try { const cred = await navigator.credentials.get({ password: true, mediation: 'silent', signal: AbortSignal.timeout(5000), }); if (!cred) return showSignInButton(); await postJson('/session', { id: cred.id, password: cred.password }); showSignedInState(cred.name ?? cred.id); } catch (err) { if (err.name === 'TimeoutError' || err.name === 'AbortError') return showSignInButton(); throw err; }}
window.addEventListener('load', trySilentSignIn);Branch on both TimeoutError and AbortError: AbortSignal.timeout() rejects with the former, a manual AbortController with the latter.
Remembering a password after a successful form sign-in
Section titled “Remembering a password after a successful form sign-in”store() after the server accepted the credentials is what lets the next visit’s silent get() succeed. Build the PasswordCredential from the form so the autocomplete="username" and autocomplete="current-password" fields supply id and password.
document.querySelector('#sign-in').addEventListener('submit', async (event) => { event.preventDefault(); const form = event.currentTarget; const ok = await postForm('/session', new FormData(form)); if (!ok) return showError('Wrong username or password');
if ('PasswordCredential' in window) { try { await navigator.credentials.store(new PasswordCredential(form)); } catch (err) { console.warn(`store() failed: ${err.name}`); // sign-in already succeeded } } location.assign('/home');});Chrome 51+ is the only engine where this branch runs; in Firefox and Safari the form submits normally and the browser’s own password manager offers to save.
Clearing silent access on sign-out, including Safari 13 to 16
Section titled “Clearing silent access on sign-out, including Safari 13 to 16”preventSilentAccess() sets the origin’s flag so the next get() requires mediation. A typeof check passes in Safari 13 to 16 even though every call rejects with NotSupportedError, so catch that one name and treat it as done.
async function signOut() { await fetch('/session', { method: 'DELETE' }); if (typeof navigator.credentials?.preventSilentAccess === 'function') { try { await navigator.credentials.preventSilentAccess(); } catch (err) { if (err.name !== 'NotSupportedError') throw err; } } location.assign('/');}Only NotSupportedError is swallowed; an InvalidStateError from a detached document still surfaces.
See also
Section titled “See also”- WebAuthn and passkeys, for the
PublicKeyCredentialtype - Payment Request API, the kind of step that calls for
mediation: "required"first - Web app manifest id: a stable PWA identity, identifies the installed app, not the user
- Credential Management Level 1: Request a Credential (w3.org)
- The Credential Management API (web.dev)
- Chrome Platform Status: Credential Management API (chromestatus.com)
Specifications
| Specification | Status |
|---|---|
| Credential Management Level 1: get() method | W3C |
| Credential Management Level 1: preventSilentAccess() method | W3C |