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

… keys (elastic#132402)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>

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,31 +55,53 @@ 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 the edit. They are 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
 * Updating a rule
 
+When you disable a rule, it retains the associated API key which is re-used when 
+the rule is enabled. If the API key is missing when you enable the rule (for 
+example, in the case of imported rules), it generates a new key that has your 
+security privileges.
+
+You can update an API key manually in 
+**{stack-manage-app} > {rules-ui}** or in the rule details page by selecting 
+**Update API key** in the actions menu.
+
 [IMPORTANT]
 ==============================================
-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 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 
+modifies the rule, it will begin running with increased privileges.
 ==============================================