[DOCS] Updates alerting authorization docs with info on retaining API…

… keys.

docs/user/alerting/alerting-setup.asciidoc

@@ -5,35 +5,47 @@
 <titleabbrev>Set up</titleabbrev>
 ++++
 
-Alerting is automatically enabled in {kib}, but might require some additional configuration.
+Alerting is automatically enabled in {kib}, but might require some additional 
+configuration.
 
 [float]
 [[alerting-prerequisites]]
 === Prerequisites
 If you are using an *on-premises* Elastic Stack deployment:
 
-* In the kibana.yml configuration file, add the <<general-alert-action-settings,`xpack.encryptedSavedObjects.encryptionKey`>> setting.
-* For emails to have a footer with a link back to {kib}, set the <<server-publicBaseUrl, `server.publicBaseUrl`>> configuration setting.
+* In the kibana.yml configuration file, add the 
+<<general-alert-action-settings,`xpack.encryptedSavedObjects.encryptionKey`>> 
+setting.
+* For emails to have a footer with a link back to {kib}, set the 
+<<server-publicBaseUrl, `server.publicBaseUrl`>> configuration setting.
 
-If you are using an *on-premises* Elastic Stack deployment with <<using-kibana-with-security, *security*>>:
+If you are using an *on-premises* Elastic Stack deployment with 
+<<using-kibana-with-security, *security*>>:
 
-* If you are unable to access {kib} Alerting, ensure that you have not {ref}/security-settings.html#api-key-service-settings[explicitly disabled API keys].
+* If you are unable to access {kib} Alerting, ensure that you have not 
+{ref}/security-settings.html#api-key-service-settings[explicitly disabled API keys].
 
-The alerting framework uses queries that require the `search.allow_expensive_queries` setting to be `true`. See the scripts {ref}/query-dsl-script-query.html#_allow_expensive_queries_4[documentation]. 
+The alerting framework uses queries that require the 
+`search.allow_expensive_queries` setting to be `true`. See the scripts 
+{ref}/query-dsl-script-query.html#_allow_expensive_queries_4[documentation]. 
 
 [float]
 [[alerting-setup-production]]
 === Production considerations and scaling guidance
 
-When relying on alerting and actions as mission critical services, make sure you follow the <<alerting-production-considerations,Alerting production considerations>>.
+When relying on alerting and actions as mission critical services, make sure you 
+follow the 
+<<alerting-production-considerations,Alerting production considerations>>.
 
-See <<alerting-scaling-guidance>> for more information on the scalability of Alerting.
+See <<alerting-scaling-guidance>> for more information on the scalability of 
+Alerting.
 
 [float]
 [[alerting-security]]
 === Security
 
-To access alerting in a space, a user must have access to one of the following features:
+To access alerting in a space, a user must have access to one of the following 
+features:
 
 * Alerting
 * <<xpack-apm,*APM*>>
@@ -43,32 +55,56 @@ To access alerting in a space, a user must have access to one of the following f
 * <<xpack-siem,*Security*>>
 * <<uptime-app,*Uptime*>>
 
-See <<kibana-feature-privileges, feature privileges>> for more information on configuring roles that provide access to these features.
-Also note that a user will need +read+ privileges for the *Actions and Connectors* feature to attach actions to a rule or to edit a rule that has an action attached to it.
+See <<kibana-feature-privileges, feature privileges>> for more information on 
+configuring roles that provide access to these features.
+Also note that a user will need +read+ privileges for the 
+*Actions and Connectors* feature to attach actions to a rule or to edit a rule 
+that has an action attached to it.
 
 [float]
 [[alerting-restricting-actions]]
 ==== Restrict actions
 
-For security reasons you may wish to limit the extent to which {kib} can connect to external services. <<action-settings>> allows you to disable certain <<action-types>> and allowlist the hostnames that {kib} can connect with.
+For security reasons you may wish to limit the extent to which {kib} can connect 
+to external services. <<action-settings>> allows you to disable certain 
+<<action-types>> and allowlist the hostnames that {kib} can connect with.
 
 [float]
 [[alerting-spaces]]
 === Space isolation
 
-Rules and connectors are isolated to the {kib} space in which they were created. A rule or connector created in one space will not be visible in another. 
+Rules and connectors are isolated to the {kib} space in which they were created. 
+A rule or connector created in one space will not be visible in another. 
 
 [float]
 [[alerting-authorization]]
 === Authorization
 
-Rules are authorized using an <<api-keys,API key>> associated with the last user to edit the rule. This API key captures a snapshot of the user's privileges at the time of edit and is subsequently used to run all background tasks associated with the rule, including condition checks like {es} queries and triggered actions. The following rule actions will re-generate the API key:
+Rules are authorized using an <<api-keys,API key>> associated with the last user 
+to edit the rule. This API key captures a snapshot of the user's privileges at 
+the time of edit and is subsequently used to run all background tasks associated 
+with the rule, including condition checks like {es} queries and triggered 
+actions. The following rule actions will re-generate the API key:
 
 * Creating a rule
-* Enabling a disabled rule
 * Updating a rule
 
+Disabling a rule retains the associated API key which will be re-used when the 
+rule is enabled. If the disabled rule is missing an API key, then enabling the 
+rule will generate a new API key associated with the privileges of the user 
+who enabled the rule.
+
+You can update an API key manually in 
+**Stack Management > Rules and Connectors** by selecting **Update API key** in 
+the actions menu of the respective rule.
+
+[role="screenshot"]
+image::images/update-api-key.png[A screenshot of a rule with the action menu open]
+
 [IMPORTANT]
 ==============================================
-If a rule requires certain privileges, such as index privileges, to run, and a user without those privileges updates, disables, or re-enables the rule, the rule will no longer function. Conversely, if a user with greater or administrator privileges modifies the rule, it will begin running with increased privileges.
+If a rule requires certain privileges, such as index privileges, to run, and a 
+user without those privileges updates the rule, the rule will no longer 
+function. Conversely, if a user with greater or administrator privileges updates 
+the rule, it will begin running with increased privileges.
 ==============================================