diff --git a/files/en-us/web/api/credential_management_api/credential-types.svg b/files/en-us/web/api/credential_management_api/credential-types.svg
new file mode 100644
index 000000000000000..b254bb7cc7788b8
--- /dev/null
+++ b/files/en-us/web/api/credential_management_api/credential-types.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/files/en-us/web/api/credential_management_api/index.md b/files/en-us/web/api/credential_management_api/index.md
index 89e784d83674a84..de954941d322889 100644
--- a/files/en-us/web/api/credential_management_api/index.md
+++ b/files/en-us/web/api/credential_management_api/index.md
@@ -12,19 +12,95 @@ spec-urls: https://w3c.github.io/webappsec-credential-management/
{{DefaultAPISidebar("Credential Management API")}}{{securecontext_header}}
-The Credential Management API lets a website store and retrieve password, public key, 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.
+The Credential Management API enables a website to create, store, and retrieve {{glossary("credential", "credentials")}}. A credential is an item which enables a system to make an {{glossary("authentication")}} decision: for example, to decide whether to sign a user into an account. We can think of it as a piece of evidence that a user presents to a website to demonstrate that they really are the person they are claiming to be.
## Concepts and usage
-This API lets websites interact with a user agent's password system directly so that websites can deal in a uniform way with site credentials and user agents can provide better assistance with the management of their credentials. For example, user agents have a particularly hard time dealing with federated identity providers or esoteric sign-in mechanisms.
+The central interface is the {{domxref("CredentialsContainer")}}, which is accessed through the {{domxref("navigator.credentials")}} property, and which provides three main functions:
-To address these problems, the Credential Management API provides ways for a website to store and retrieve different types of credentials. This gives users capabilities such as seeing the federated account they used to sign on to a site, or resuming a session without the explicit sign-in flow of an expired session.
+- {{domxref("CredentialsContainer.create", "create()")}}: create a new credential.
+- {{domxref("CredentialsContainer.store", "store()")}}: store a new credential locally.
+- {{domxref("CredentialsContainer.get", "get()")}}: retrieve a credential, which can then be used to log a user in.
-> **Note:** This API is restricted to top-level contexts. Calls to `get()` and `store()` within an `