[8.2] Updates warning about editing rules using API authentication (b…

…ackport #4110) (#4159) * 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 <[email protected]> * Applies TW feedback * Updates notes to address both scenarios * Removes extra period --------- Co-authored-by: Benjamin Ironside Goldstein <[email protected]> (cherry picked from commit 783ce5a) # Conflicts: # docs/detections/api/rules/rules-api-create.asciidoc # docs/detections/api/rules/rules-api-import.asciidoc * Resolves conflict * Removes frontmatter --------- Co-authored-by: natasha-moore-elastic <[email protected]> Co-authored-by: natasha-moore-elastic <[email protected]>
elastic · Nov 1, 2023 · e61f9c0 · e61f9c0
1 parent b073e19
commit e61f9c0
Show file tree

Hide file tree

Showing 5 changed files with 55 additions and 4 deletions.
diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc
@@ -14,7 +14,12 @@ NOTE: Console supports only {es} APIs and doesn't allow interactions with {kib}
 
 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.
 
@@ -147,7 +152,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.
 
@@ -230,6 +240,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
@@ -1,7 +1,12 @@
 [[rules-api-create]]
 === Create 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.
+====
 
 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,6 +6,13 @@ Imports rules from an `.ndjson` file. The following configuration items are also
 * Actions
 * Exception lists
 
+[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: Console supports {es} APIs only. Console doesn't allow interactions with {kib} APIs. You must use `curl` or another HTTP tool instead. For more information, refer to {kibana-ref}/console-kibana.html[Run {es} API requests]. Please also note this API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
 
 NOTE: You need at least `Read` privileges for the `Action and Connectors` feature to import rules with actions. If you're importing rules without actions, `Action and Connectors` feature privileges are not required. 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
@@ -33,6 +33,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.