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-bulk-actions.asciidoc # docs/detections/api/rules/rules-api-create.asciidoc # docs/detections/api/rules/rules-api-import.asciidoc
elastic · Nov 1, 2023 · 1bc1a09 · 1bc1a09
1 parent 3822706
commit 1bc1a09
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 1 deletion.
diff --git a/docs/detections/api/rules/rules-api-bulk-actions.asciidoc b/docs/detections/api/rules/rules-api-bulk-actions.asciidoc
@@ -10,7 +10,18 @@ NOTE: Console supports only {es} APIs and doesn't allow interactions with {kib}
 [[bulk-actions-rules-api-create]]
 ==== Bulk create
 
+<<<<<<< HEAD
 WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+=======
+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]
+====
+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.
+====
+>>>>>>> 783ce5a (Updates warning about editing rules using API authentication (#4110))
 
 Creates new rules.
 
@@ -135,7 +146,18 @@ A JSON array containing the deleted rules.
 [[bulk-actions-rules-api-update]]
 ==== Bulk update
 
+<<<<<<< HEAD
 WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+=======
+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]
+====
+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.
+====
+>>>>>>> 783ce5a (Updates warning about editing rules using API authentication (#4110))
 
 Updates multiple rules.
 
@@ -216,7 +238,18 @@ A JSON array containing the updated rules.
 [[bulk-actions-rules-api-action]]
 ==== Bulk action
 
+<<<<<<< HEAD
 Applies a bulk action to multiple rules. The bulk action is applied to all rules that match the filter.
+=======
+[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.
+>>>>>>> 783ce5a (Updates warning about editing rules using API authentication (#4110))
 
 [discrete]
 ===== Request URL

diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc
@@ -1,7 +1,21 @@
 [[rules-api-create]]
 === Create rule
 
+<<<<<<< HEAD
 WARNING: This API supports {kibana-ref}/api.html#token-api-authentication[Token-based authentication] only.
+=======
+:frontmatter-description: Create a new detection rule.
+:frontmatter-tags-products: [security, alerting]
+:frontmatter-tags-content-type: [reference]
+:frontmatter-tags-user-goals: [manage]
+
+[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.
+====
+>>>>>>> 783ce5a (Updates warning about editing rules using API authentication (#4110))
 
 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,16 @@ Imports rules from an `.ndjson` file. The following configuration items are also
 * Actions
 * Exception lists
 
+<<<<<<< HEAD
 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.
+=======
+[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.
+====
+>>>>>>> 783ce5a (Updates warning about editing rules using API authentication (#4110))
 
 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.