diff --git a/x-pack/plugins/alerts/README.md b/x-pack/plugins/alerts/README.md
index 83a1ff952cb5de..c57216603665dc 100644
--- a/x-pack/plugins/alerts/README.md
+++ b/x-pack/plugins/alerts/README.md
@@ -13,6 +13,7 @@ Table of Contents
 - [Kibana alerting](#kibana-alerting)
 	- [Terminology](#terminology)
 	- [Usage](#usage)
+	- [Alerts API keys](#alerts-api-keys)
 	- [Limitations](#limitations)
 	- [Alert types](#alert-types)
 		- [Methods](#methods)
@@ -53,6 +54,17 @@ A Kibana alert detects a condition and executes one or more actions when that co
 2. Configure feature level privileges using RBAC 
 3. Create an alert using the RESTful API [Documentation](https://www.elastic.co/guide/en/kibana/master/alerts-api-update.html) (see alerts -> create).
 
+## Alerts API keys
+
+When we create an alert, we generate a new API key.
+
+When we update, enable, or disable an alert, we must invalidate the old API key and create a new one.
+
+To manage the invalidation process for API keys, we use the saved object `api_key_pending_invalidation`.  This object stores all API keys that were marked for invalidation when alerts were updated.
+For security plugin invalidation, we schedule a task to check if the`api_key_pending_invalidation` saved object contains new API keys that are marked for invalidation earlier than the configured delay.  The default value for running the task is 5 mins.
+To change the schedule for the invalidation task, use the kibana.yml configuration option `xpack.alerts.invalidateApiKeysTask.interval`.
+To change the default delay for the API key invalidation, use the kibana.yml configuration option `xpack.alerts.invalidateApiKeysTask.removalDelay`.
+
 ## Limitations
 
 When security is enabled, an SSL connection to Elasticsearch is required in order to use alerting.