Updates warning about editing rules using API authentication (#4110)

* Updates warning about editing rules using API authentication * Apply suggestions from TW review Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> * Applies TW feedback * Updates notes to address both scenarios * Removes extra period --------- Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com>
elastic · Nov 1, 2023 · 783ce5a · 783ce5a
1 parent 7690424
commit 783ce5a
Show file tree

Hide file tree

Showing 5 changed files with 54 additions and 5 deletions.
diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc
@@ -12,7 +12,12 @@ You can bulk create, update, and delete rules.
 
 IMPORTANT: This API has been deprecated since version 8.2, and is scheduled for end of life in Q4 2023. Please use the <<bulk-actions-rules-api-action, bulk action API>> instead.
 
-WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+[WARNING]
+====
+When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
+
+If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
+====
 
 Creates new rules.
 
@@ -145,7 +150,12 @@ A JSON array containing the deleted rules.
 
 IMPORTANT: This API has been deprecated since version 8.2, and is scheduled for end of life in Q4 2023. Please use the <<bulk-actions-rules-api-action, bulk action API>> instead.
 
-WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+[WARNING]
+====
+When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
+
+If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
+====
 
 Updates multiple rules.
 
@@ -228,6 +238,13 @@ A JSON array containing the updated rules.
 [[bulk-actions-rules-api-action]]
 ==== Bulk action
 
+[WARNING]
+====
+When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
+
+If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
+====
+
 Applies a bulk action to multiple rules. The bulk action is applied to all rules that match the filter or to the list of rules by their IDs.
 
 [discrete]

diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc
@@ -6,7 +6,12 @@
 :frontmatter-tags-content-type: [reference]
 :frontmatter-tags-user-goals: [manage]
 
-WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+[WARNING]
+====
+When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
+
+If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
+====
 
 Creates a new detection rule.
 

diff --git a/docs/detections/api/rules/rules-api-import.asciidoc b/docs/detections/api/rules/rules-api-import.asciidoc
@@ -6,7 +6,12 @@ Imports rules from an `.ndjson` file. The following configuration items are also
 * Actions
 * Exception lists
 
-NOTE: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+[WARNING]
+====
+When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
+
+If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
+====
 
 NOTE: To import rules with actions, you need at least `Read` privileges for the `Action and Connectors` feature. To overwrite or add new connectors, you need `All` privileges for the `Actions and Connectors` feature. To import rules without actions,  you don't need `Actions and Connectors` privileges. Refer to <<enable-detections-ui>> for more information.
 

diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc
@@ -31,6 +31,23 @@ the status of Elastic <<prebuilt-rules, prebuilt rules>>
 TIP: You can view and download a Detections API Postman collection
 https://github.com/elastic/examples/tree/master/Security%20Analytics/SIEM-examples/Detections-API[here].
 
+[float]
+=== Authentication
+This API supports both key- and token-based authentication.
+
+To use key-based authentication, create an {kibana-ref}/api-keys.html[API key], then specify the key in the header of your API calls.
+
+To use token-based authentication, provide a username and password; this automatically creates an API key that matches the current user's privileges.
+
+In both cases, the API key is subsequently used for authorization when the rule runs.
+
+[WARNING]
+====
+If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
+
+If the key that created the rule gets deleted, or the user that created the rule becomes inactive, the rule will stop running.
+====
+
 [float]
 === Kibana role requirements
 

diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc
@@ -1,7 +1,12 @@
 [[rules-api-update]]
 === Update rule
 
-WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+[WARNING]
+====
+When used with {kibana-ref}/api-keys.html[API key] authentication, the user's key gets assigned to the affected rules. If the user's key gets deleted or the user becomes inactive, the rules will stop running.
+
+If the API key that is used for authorization has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
+====
 
 Updates an existing detection rule.