[DOCS] Add security privileges to index API docs (#68071)

docs/reference/indices/add-alias.asciidoc

@@ -26,6 +26,11 @@ PUT /my-index-000001/_alias/alias1
 
 `POST /<index>/_aliases/<alias>`
 
+[[add-alias-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for both the index and index alias.
 
 [[add-alias-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/alias-exists.asciidoc

@@ -23,6 +23,13 @@ HEAD /_alias/alias1
 
 `HEAD /<index>/_alias/<alias>`
 
+[[alias-exists-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
+for the index alias. If you specify an index, you must also have
+`view_index_metadata` or `manage` index privilege for the index.
 
 [[alias-exists-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/aliases.asciidoc

@@ -25,6 +25,17 @@ POST /_aliases
 
 `POST /_aliases`
 
+[[indices-aliases-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the following
+<<privileges-list-indices,index privileges>>:
+
+** To use the `add` or `remove` action, you must have the `manage` index
+privilege for both the index and index alias.
+
+** To use the `remove_index` action, you must have the `manage` index privilege
+for the index.
 
 [[indices-aliases-api-desc]]
 ==== {api-description-title}

docs/reference/indices/analyze.asciidoc

@@ -28,6 +28,11 @@ GET /_analyze
 
 `POST /<index>/_analyze`
 
+[[analyze-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the specified index.
 
 [[analyze-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/apis/freeze.asciidoc

@@ -13,8 +13,11 @@ Freezes an index.
 
 `POST /<index>/_freeze`
 
-//[[freeze-index-api-prereqs]]
-//==== {api-prereq-title}
+[[freeze-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the target index or index alias.
 
 [[freeze-index-api-desc]]
 ==== {api-description-title}

docs/reference/indices/apis/unfreeze.asciidoc

@@ -13,8 +13,11 @@ Unfreezes an index.
 
 `POST /<index>/_unfreeze`
 
-//[[unfreeze-index-api-prereqs]]
-//==== {api-prereq-title}
+[[unfreeze-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the target index or index alias.
 
 [[unfreeze-index-api-desc]]
 ==== {api-description-title}

docs/reference/indices/clearcache.asciidoc

@@ -21,6 +21,12 @@ POST /my-index-000001/_cache/clear
 
 `POST /_cache/clear`
 
+[[clear-cache-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the target data stream, index,
+or index alias.
 
 [[clear-cache-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/clone-index.asciidoc

@@ -20,13 +20,14 @@ POST /my-index-000001/_clone/cloned-my-index-000001
 
 `PUT /<index>/_clone/<target-index>`
 
-
 [[clone-index-api-prereqs]]
 ==== {api-prereq-title}
 
-To clone an index,
-the index must be marked as read-only
-and have a <<cluster-health,cluster health>> status of `green`.
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the index you want to clone.
+
+* To clone an index, the index must be marked as read-only and have a
+<<cluster-health,cluster health>> status of `green`.
 
 For example,
 the following request prevents write operations on `my_source_index`

docs/reference/indices/close.asciidoc

@@ -18,6 +18,11 @@ POST /my-index-000001/_close
 
 `POST /<index>/_close`
 
+[[close-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the target index or index alias.
 
 [[close-index-api-desc]]
 ==== {api-description-title}

docs/reference/indices/create-index.asciidoc

@@ -17,6 +17,12 @@ PUT /my-index-000001
 
 `PUT /<index>`
 
+[[indices-create-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `create_index`
+or `manage` <<privileges-list-indices,index privilege>> for the target index.
+
 [[indices-create-api-desc]]
 ==== {api-description-title}
 You can use the create index API to add a new index to an {es} cluster. When

docs/reference/indices/dangling-index-delete.asciidoc

@@ -15,6 +15,12 @@ DELETE /_dangling/<index-uuid>?accept_data_loss=true
 --------------------------------------------------
 // TEST[skip:Difficult to set up]
 
+[[dangling-index-delete-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-cluster,cluster privilege>> to use this API.
+
 [[dangling-index-delete-api-desc]]
 ==== {api-description-title}
 

docs/reference/indices/dangling-index-import.asciidoc

@@ -15,6 +15,12 @@ POST /_dangling/<index-uuid>?accept_data_loss=true
 --------------------------------------------------
 // TEST[skip:Difficult to set up]
 
+[[dangling-index-import-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-cluster,cluster privilege>> to use this API.
+
 [[dangling-index-import-api-desc]]
 ==== {api-description-title}
 

docs/reference/indices/dangling-indices-list.asciidoc

@@ -15,6 +15,12 @@ GET /_dangling
 --------------------------------------------------
 // TEST[skip:TBD]
 
+[[dangling-indices-list-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-cluster,cluster privilege>> to use this API.
+
 [[dangling-indices-list-api-desc]]
 ==== {api-description-title}
 

docs/reference/indices/delete-alias.asciidoc

@@ -22,6 +22,11 @@ DELETE /my-index-000001/_alias/alias1
 
 `DELETE /<index>/_aliases/<alias>`
 
+[[delete-alias-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for both the index and index alias.
 
 [[delete-alias-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/delete-component-template.asciidoc

@@ -32,6 +32,12 @@ DELETE _component_template/template_1
 
 `DELETE /_component_template/<component-template>`
 
+[[delete-component-template-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[delete-component-template-api-desc]]
 ==== {api-description-title}

docs/reference/indices/delete-index-template-v1.asciidoc

@@ -36,6 +36,12 @@ DELETE /_template/my-legacy-index-template
 
 `DELETE /_template/<legacy-index-template>`
 
+[[delete-template-api-v1-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[delete-template-api-v1-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/delete-index-template.asciidoc

@@ -33,6 +33,12 @@ DELETE /_index_template/my-index-template
 
 `DELETE /_index_template/<index-template>`
 
+[[delete-template-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[delete-template-api-desc]]
 ==== {api-description-title}

docs/reference/indices/delete-index.asciidoc

@@ -18,6 +18,11 @@ DELETE /my-index-000001
 
 `DELETE /<index>`
 
+[[delete-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `delete_index`
+or `manage` <<privileges-list-indices,index privilege>> for the target index.
 
 [[delete-index-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/flush.asciidoc

@@ -24,6 +24,12 @@ POST /my-index-000001/_flush
 
 `GET /_flush`
 
+[[flush-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `maintenance`
+or `manage` <<privileges-list-indices,index privilege>> for the target data
+stream, index, or index alias.
 
 [[flush-api-desc]]
 ==== {api-description-title}

docs/reference/indices/forcemerge.asciidoc

@@ -22,6 +22,12 @@ POST /my-index-000001/_forcemerge
 
 `POST /_forcemerge`
 
+[[forcemerge-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `maintenance`
+or `manage` <<privileges-list-indices,index privilege>> for the target data
+stream, index, or index alias.
 
 [[forcemerge-api-desc]]
 ==== {api-description-title}

docs/reference/indices/get-alias.asciidoc

@@ -25,6 +25,14 @@ GET /my-index-000001/_alias/alias1
 
 `GET /<index>/_alias/<alias>`
 
+[[get-alias-api-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
+for the index alias. If you specify an index, you must also have
+`view_index_metadata` or `manage` index privilege for the index.
+
 
 [[get-alias-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/get-component-template.asciidoc

@@ -46,6 +46,12 @@ GET /_component_template/template_1
 
 `GET /_component-template/<component-template>`
 
+[[get-component-template-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[get-component-template-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/get-field-mapping.asciidoc

@@ -24,6 +24,12 @@ GET /my-index-000001/_mapping/field/user
 
 `GET /<target>/_mapping/field/<field>`
 
+[[get-field-mapping-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
+for the target data stream, index, or index alias.
 
 [[get-field-mapping-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/get-index-template-v1.asciidoc

@@ -42,6 +42,12 @@ GET /_template/template_1
 
 `GET /_template/<index-template>`
 
+[[get-template-v1-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[get-template-v1-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/get-index-template.asciidoc

@@ -41,6 +41,12 @@ GET /_index_template/template_1
 
 `GET /_index_template/<index-template>`
 
+[[get-template-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[get-template-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/get-index.asciidoc

@@ -18,6 +18,12 @@ GET /my-index-000001
 
 `GET /<target>`
 
+[[get-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
+for the target data stream, index, or index alias.
 
 [[get-index-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/get-mapping.asciidoc

@@ -20,6 +20,12 @@ GET /my-index-000001/_mapping
 
 `GET /<target>/_mapping`
 
+[[get-mapping-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
+for the target data stream, index, or index alias.
 
 [[get-mapping-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/get-settings.asciidoc

@@ -21,6 +21,12 @@ GET /my-index-000001/_settings
 
 `GET /<target>/_settings/<setting>`
 
+[[get-index-settings-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata`, `monitor`, or `manage` <<privileges-list-indices,index
+privilege>> for the target data stream, index, or index alias.
 
 [[get-index-settings-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/index-template-exists-v1.asciidoc

@@ -24,6 +24,12 @@ HEAD /_template/template_1
 
 `HEAD /_template/<index-template>`
 
+[[template-exists-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[template-exists-api-desc]]
 ==== {api-description-title}

docs/reference/indices/indices-exists.asciidoc

@@ -18,16 +18,22 @@ HEAD /my-index-000001
 [[indices-exists-api-request]]
 ==== {api-request-title}
 
-`HEAD /<index>`
+`HEAD /<target>`
 
+[[indices-exists-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
+for the target data stream, index, or index alias.
 
 [[indices-exists-api-path-params]]
 ==== {api-path-parms-title}
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
-+
-IMPORTANT: This parameter does not distinguish between an index name and <<indices-aliases,alias>>,
-i.e. status code `200` is also returned if an alias exists with that name.
+`<target>`::
+(Optional, string)
+Comma-separated list of data streams, indices, and index aliases used to limit
+the request. Wildcard expressions (`*`) are supported.
 
 
 [[indices-exists-api-query-params]]

docs/reference/indices/open-close.asciidoc

@@ -20,6 +20,12 @@ POST /my-index-000001/_open
 
 `POST /<target>/_open`
 
+[[open-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the target data stream, index,
+or index alias.
 
 [[open-index-api-desc]]
 ==== {api-description-title}

docs/reference/indices/put-component-template.asciidoc

@@ -51,6 +51,12 @@ DELETE _component_template/template_*
 
 `PUT /_component_template/<component-template>`
 
+[[put-component-template-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[put-component-template-api-desc]]
 ==== {api-description-title}

docs/reference/indices/put-index-template-v1.asciidoc

@@ -51,6 +51,13 @@ DELETE _template/template_*
 
 `PUT /_template/<index-template>`
 
+[[put-index-template-v1-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
+
 
 [[put-index-template-v1-api-desc]]
 ==== {api-description-title}

docs/reference/indices/put-index-template.asciidoc

@@ -38,6 +38,12 @@ DELETE _index_template/template_*
 
 `PUT /_index_template/<index-template>`
 
+[[put-index-template-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[put-index-template-api-desc]]
 ==== {api-description-title}

docs/reference/indices/put-mapping.asciidoc

@@ -29,6 +29,17 @@ PUT /my-index-000001/_mapping
 
 `PUT /_mapping`
 
+[[put-mapping-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the target data stream, index,
+or index alias.
++
+deprecated:[7.9] If the request targets an index or index alias, you can also
+update its mapping with the `create`, `create_doc`, `index`, or `write` index
+privilege.
+
 
 [[put-mapping-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/recovery.asciidoc

@@ -23,6 +23,12 @@ GET /my-index-000001/_recovery
 
 `GET /_recovery`
 
+[[index-recovery-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `monitor` or
+`manage` <<privileges-list-indices,index privilege>> for the target data stream,
+index, or index alias.
 
 [[index-recovery-api-desc]]
 ==== {api-description-title}

docs/reference/indices/refresh.asciidoc

@@ -25,6 +25,12 @@ POST /my-index-000001/_refresh
 
 `GET /_refresh`
 
+[[refresh-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `maintenance`
+or `manage` <<privileges-list-indices,index privilege>> for the target data
+stream, index, or index alias.
 
 [[refresh-api-desc]]
 ==== {api-description-title}

docs/reference/indices/resolve.asciidoc

@@ -56,6 +56,12 @@ GET /_resolve/index/my-index-*
 
 `GET /_resolve/index/<name>`
 
+[[resolve-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
+for the target data stream, index, or index alias.
 
 [[resolve-index-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/rollover-index.asciidoc

@@ -33,6 +33,11 @@ POST /alias1/_rollover/my-index-000002
 
 `POST /<rollover-target>/_rollover/`
 
+[[rollover-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the rollover target.
 
 [[rollover-index-api-desc]]
 ==== {api-description-title}

docs/reference/indices/segments.asciidoc

@@ -22,6 +22,12 @@ GET /my-index-000001/_segments
 
 `GET /_segments`
 
+[[index-segments-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `monitor` or
+`manage` <<privileges-list-indices,index privilege>> for the target data stream,
+index, or index alias.
 
 [[index-segments-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/shard-stores.asciidoc

@@ -23,6 +23,12 @@ GET /my-index-000001/_shard_stores
 
 `GET /_shard_stores`
 
+[[index-shard-stores-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `monitor` or
+`manage` <<privileges-list-indices,index privilege>> for the target data stream,
+index, or index alias.
 
 [[index-shard-stores-api-desc]]
 ==== {api-description-title}

docs/reference/indices/shrink-index.asciidoc

@@ -25,11 +25,14 @@ POST /my-index-000001/_shrink/shrunk-my-index-000001
 [[shrink-index-api-prereqs]]
 ==== {api-prereq-title}
 
-Before you can shrink an index:
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the index.
 
-* The index must be read-only.
-* All primary shards for the index must reside on the same node.
-* The index must have a `green` <<cluster-health,health status>>.
+* Before you can shrink an index:
+
+** The index must be read-only.
+** All primary shards for the index must reside on the same node.
+** The index must have a `green` <<cluster-health,health status>>.
 
 To make shard allocation easier, we recommend you also remove the index's
 replica shards. You can later re-add replica shards as part of the shrink

docs/reference/indices/simulate-index.asciidoc

@@ -41,6 +41,12 @@ POST /_index_template/_simulate_index/my-index-000001
 
 `POST /_index_template/_simulate_index/<index>`
 
+[[simulate-index-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[simulate-index-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/simulate-template.asciidoc

@@ -62,6 +62,12 @@ POST /_index_template/_simulate/template_1
 
 `POST /_index_template/_simulate/<index-template>`
 
+[[simulate-template-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the
+`manage_index_templates` or `manage` <<privileges-list-cluster,cluster
+privilege>> to use this API.
 
 [[simulate-template-api-path-params]]
 ==== {api-path-parms-title}

docs/reference/indices/split-index.asciidoc

@@ -29,11 +29,13 @@ POST /my-index-000001/_split/split-my-index-000001
 [[split-index-api-prereqs]]
 ==== {api-prereq-title}
 
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the index.
 
-Before you can split an index:
+* Before you can split an index:
 
-* The index must be read-only.
-* The <<cluster-health, cluster health>> status must be green.
+** The index must be read-only.
+** The <<cluster-health, cluster health>> status must be green.
 
 You can do make an index read-only
 with the following request:

docs/reference/indices/stats.asciidoc

@@ -23,6 +23,12 @@ GET /my-index-000001/_stats
 
 `GET /_stats`
 
+[[index-stats-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `monitor` or
+`manage` <<privileges-list-indices,index privilege>> for the target data stream,
+index, or index alias.
 
 [[index-stats-api-desc]]
 ==== {api-description-title}

docs/reference/indices/update-settings.asciidoc

@@ -26,6 +26,12 @@ PUT /my-index-000001/_settings
 
 `PUT /<target>/_settings`
 
+[[update-index-settings-api-prereqs]]
+==== {api-prereq-title}
+
+* If the {es} {security-features} are enabled, you must have the `manage`
+<<privileges-list-indices,index privilege>> for the target data stream, index,
+or index alias.
 
 [[update-index-settings-api-path-params]]
 ==== {api-path-parms-title}