[DOCS] Reformats the security APIs (#45124)

x-pack/docs/en/rest-api/security/authenticate.asciidoc

@@ -5,23 +5,28 @@
 <titleabbrev>Authenticate</titleabbrev>
 ++++
 
-The Authenticate API enables you to submit a request with a basic auth header to
+Enables you to submit a request with a basic auth header to
 authenticate a user and retrieve information about the authenticated user.
 
 
-==== Request
+[[security-api-authenticate-request]]
+==== {api-request-title}
 
 `GET /_security/_authenticate`
 
-
-==== Description
+[[security-api-authenticate-desc]]
+==== {api-description-title}
 
 A successful call returns a JSON structure that shows user information such as their username, the roles that are
 assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user.
 
+[[security-api-authenticate-response-codes]]
+==== {api-response-codes-title}
+
 If the user cannot be authenticated, this API returns a 401 status code.
 
-==== Examples
+[[security-api-authenticate-example]]
+==== {api-examples-title}
 
 To authenticate a user, submit a GET request to the
 `/_security/_authenticate` endpoint:

x-pack/docs/en/rest-api/security/change-password.asciidoc

@@ -7,14 +7,22 @@
 
 Changes the passwords of users in the native realm and built-in users.
 
-==== Request
+[[security-api-change-password-request]]
+==== {api-request-title}
 
 `POST /_security/user/_password` +
 
 `POST /_security/user/<username>/_password`
 
 
-==== Description
+[[security-api-change-password-prereqs]]
+==== {api-prereq-title}
+
+* Every user can change their own password. Users with the `manage_security`
+privilege can change passwords of other users.
+
+[[security-api-change-password-desc]]
+==== {api-description-title}
 
 You can use the <<security-api-put-user,create user API>> to update everything 
 but a user's `username` and `password`. This API changes a user's password.
@@ -23,26 +31,23 @@ For more information about the native realm, see
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
 
-==== Path Parameters
+[[security-api-change-password-path-params]]
+==== {api-path-parms-title}
 
 `username`::
-  (string) The user whose password you want to change. If you do not specify
+  (Optional, string) The user whose password you want to change. If you do not specify
   this parameter, the password is changed for the current user.
 
 
-==== Request Body
-
-`password` (required)::
-  (string) The new password value.
+[[security-api-change-password-request-body]]
+==== {api-request-body-title}
 
-
-==== Authorization
-
-Every user can change their own password. Users with the `manage_security`
-privilege can change passwords of other users.
+`password`::
+  (Required, string) The new password value.
 
 
-==== Examples
+[[security-api-change-password-example]]
+==== {api-examples-title}
 
 The following example updates the password for the `jacknich` user:
 

x-pack/docs/en/rest-api/security/clear-cache.asciidoc

@@ -5,36 +5,42 @@
 <titleabbrev>Clear cache</titleabbrev>
 ++++
 
-The clear cache API evicts users from the user cache. You can completely clear
+Evicts users from the user cache. You can completely clear
 the cache or evict specific users.
 
-==== Request
+[[security-api-clear-request]]
+==== {api-request-title}
 
 `POST /_security/realm/<realms>/_clear_cache` +
 
 `POST /_security/realm/<realms>/_clear_cache?usernames=<usernames>`
 
 
-==== Description
+[[security-api-clear-desc]]
+==== {api-description-title}
 
 User credentials are cached in memory on each node to avoid connecting to a
 remote authentication service or hitting the disk for every incoming request.
 There are realm settings that you can use to configure the user cache. For more
-information, see {xpack-ref}/controlling-user-cache.html[Controlling the User Cache].
+information, see
+{stack-ov}/controlling-user-cache.html[Controlling the user cache].
 
 To evict roles from the role cache, see the 
-<<security-api-clear-role-cache,Clear Roles Cache API>>.
+<<security-api-clear-role-cache,Clear roles cache API>>.
 
-==== Path Parameters
+[[security-api-clear-path-params]]
+==== {api-path-parms-title}
 
-`realms` (required)::
-  (list) A comma-separated list of the realms to clear.
+`realms`::
+  (Required, list) A comma-separated list of the realms to clear.
 
 `usernames`::
-  (list) A comma-separated list of the users to clear from the cache. If you
-  do not specify this parameter, the API evicts all users from the user cache.
+  (Optional, list) A comma-separated list of the users to clear from the cache.
+  If you do not specify this parameter, the API evicts all users from the user
+  cache.
 
-==== Examples
+[[security-api-clear-example]]
+==== {api-examples-title}
 
 For example, to evict all users cached by the `file` realm:
 

x-pack/docs/en/rest-api/security/clear-roles-cache.asciidoc

@@ -7,30 +7,31 @@
 
 Evicts roles from the native role cache. 
 
-==== Request
+[[security-api-clear-role-cache-request]]
+==== {api-request-title}
 
 `POST /_security/role/<name>/_clear_cache` 
 
-==== Description
+[[security-api-clear-role-cache-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster
+privilege.
+
+[[security-api-clear-role-cache-desc]]
+==== {api-description-title}
 
 For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
-==== Path Parameters
+[[security-api-clear-role-cache-path-params]]
+==== {api-path-parms-title}
 
 `name`::
   (string) The name of the role. 
 
-
-//==== Request Body
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster
-privilege.
-
-
-==== Examples
+[[security-api-clear-role-cache-example]]
+==== {api-examples-title}
 
 The clear roles cache API evicts roles from the native role cache. For example, 
 to clear the cache for `my_admin_role`:

x-pack/docs/en/rest-api/security/create-api-keys.asciidoc

@@ -7,12 +7,19 @@
 
 Creates an API key for access without requiring basic authentication.
 
-==== Request
+[[security-api-create-api-key-request]]
+==== {api-request-title}
 
 `POST /_security/api_key`
 `PUT /_security/api_key`
 
-==== Description
+[[security-api-create-api-key-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_api_key` cluster privilege.
+
+[[security-api-create-api-key-desc]]
+==== {api-description-title}
 
 The API keys are created by the {es} API key service, which is automatically enabled
 when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
@@ -30,29 +37,31 @@ when you create the API keys.
 See <<api-key-service-settings>> for configuration settings related to API key
 service.
 
-==== Request Body
+
+[[security-api-create-api-key-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of a POST or PUT request:
 
 `name`::
 (string) Specifies the name for this API key.
 
-`role_descriptors` (optional)::
-(array-of-role-descriptor) An array of role descriptors for this API key. This
-parameter is optional. When it is not specified or is an empty array, then the API key will have
-the permissions of the authenticated user. If you supply role descriptors, they must
-be a subset of the authenticated user's permissions. The structure of role descriptor is the
-same as the request for create role API. For more details, see
+`role_descriptors`::
+(Optional, array-of-role-descriptor) An array of role descriptors for this API
+key. This parameter is optional. When it is not specified or is an empty array,
+then the API key will have the permissions of the authenticated user. If you
+supply role descriptors, they must be a subset of the authenticated user's
+permissions. The structure of role descriptor is the same as the request for
+create role API. For more details, see
 <<security-api-roles,role management APIs>>.
 
 `expiration`::
-(string) Optional expiration time for the API key. By default, API keys never expire.
-
-==== Authorization
+(Optional, string) Expiration time for the API key. By default, API keys never
+expire.
 
-To use this API, you must have at least the `manage_api_key` cluster privilege.
 
-==== Examples
+[[security-api-create-api-key-example]]
+==== {api-examples-title}
 
 The following example creates an API key:
 

x-pack/docs/en/rest-api/security/create-role-mappings.asciidoc

@@ -7,14 +7,21 @@
 
 Creates and updates role mappings.
 
-==== Request
+[[security-api-put-role-mapping-request]]
+==== {api-request-title}
 
 `POST /_security/role_mapping/<name>` +
 
 `PUT /_security/role_mapping/<name>`
 
 
-==== Description
+[[security-api-put-role-mapping-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+[[security-api-put-role-mapping-desc]]
+==== {api-description-title}
 
 Role mappings define which roles are assigned to each user. Each mapping has 
 _rules_ that identify users and a list of _roles_ that are
@@ -28,7 +35,8 @@ For more information, see
 {stack-ov}/mapping-roles.html[Mapping users and groups to roles].
 
 
-==== Path Parameters
+[[security-api-put-role-mapping-path-params]]
+==== {api-path-parms-title}
 
 `name`::
  (string) The distinct name that identifies the role mapping. The name is
@@ -36,14 +44,15 @@ For more information, see
   not affect the behavior of the mapping in any way.
 
 
-==== Request Body
+[[security-api-put-role-mapping-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of a PUT or POST request
 and pertain to adding a role mapping:
 
-`enabled` (required)::
-(boolean)  Mappings that have `enabled` set to `false` are ignored when role
-mapping is performed.
+`enabled`::
+(Required, boolean) Mappings that have `enabled` set to `false` are ignored when
+role mapping is performed.
 
 `metadata`::
 (object) Additional metadata that helps define which roles are assigned to each
@@ -62,10 +71,10 @@ mapping rules.
 The format of these objects is defined below.
 _Exactly one of `roles` or `role_templates` must be specified_.
 
-`rules` (required)::
-(object) The rules that determine which users should be matched by the mapping.
-A rule is a logical condition that is expressed by using a JSON DSL. See 
-<<role-mapping-resources>>. 
+`rules`::
+(Required, object) The rules that determine which users should be matched by the
+mapping. A rule is a logical condition that is expressed by using a JSON DSL.
+See  <<role-mapping-resources>>. 
 
 ==== Role Templates
 
@@ -91,12 +100,8 @@ array of JSON strings for the role name(s).
 
 The Examples section below demonstrates the use of templated role names.
 
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster privilege.
-
-
-==== Examples
+[[security-api-put-role-mapping-example]]
+==== {api-examples-title}
 
 The following example assigns the "user" role to all users:
 

x-pack/docs/en/rest-api/security/create-roles.asciidoc

@@ -7,27 +7,37 @@
 
 Adds and updates roles in the native realm.
 
-==== Request
+[[security-api-put-role-request]]
+==== {api-request-title}
 
 `POST /_security/role/<name>` +
 
 `PUT /_security/role/<name>`
 
 
-==== Description
+[[security-api-put-role-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster
+privilege.
+
+[[security-api-put-role-desc]]
+==== {api-description-title}
 
 The role API is generally the preferred way to manage roles, rather than using
 file-based role management. For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
 
-==== Path Parameters
+[[security-api-put-role-path-params]]
+==== {api-path-parms-title}
 
 `name`::
   (string) The name of the role.
 
 
-==== Request Body
+[[security-api-put-role-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of a PUT or POST request
 and pertain to adding a role:
@@ -67,14 +77,8 @@ For more information, see
 
 For more information, see {stack-ov}/defining-roles.html[Defining roles].
 
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster
-privilege.
-
-
-==== Examples
+[[security-api-put-role-example]]
+==== {api-examples-title}
 
 The following example adds a role called `my_admin_role`:
 

x-pack/docs/en/rest-api/security/create-users.asciidoc

@@ -9,14 +9,22 @@ Adds and updates users in the native realm. These users are commonly referred
 to as _native users_.
 
 
-==== Request
+[[security-api-put-user-request]]
+==== {api-request-title}
 
 `POST /_security/user/<username>` +
 
 `PUT /_security/user/<username>` 
 
 
-==== Description
+[[security-api-put-user-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+[[security-api-put-user-desc]]
+==== {api-description-title}
 
 When updating a user, you can update everything but its `username` and `password`. 
 To change a user's password, use the 
@@ -25,10 +33,11 @@ To change a user's password, use the
 For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
-==== Path Parameters
+[[security-api-put-user-path-params]]
+==== {api-path-parms-title}
 
-`username` (required)::
-  (string) An identifier for the user.
+`username`::
+  (Required, string) An identifier for the user.
 +
 --
 [[username-validation]]
@@ -38,14 +47,16 @@ printable symbols in the https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_bloc
 
 --
 
-==== Query Parameters
+[[security-api-put-user-query-params]]
+==== {api-query-parms-title}
 
 `refresh`::
     (string) One of `true`, `false`, or `wait_for`.
     These values have the same meaning as in the <<docs-refresh, Index API>>,
     but the default value for this API (Put User) is `true`.
 
-==== Request Body
+[[security-api-put-user-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of a POST or PUT request:
 
@@ -61,7 +72,7 @@ The following parameters can be specified in the body of a POST or PUT request:
 `metadata`::
 (object) Arbitrary metadata that you want to associate with the user.
 
-`password` ::
+`password`::
 (string) The user's password. Passwords must be at least 6 characters long.
 +
 When adding a user, one of `password` or `password_hash` is required.
@@ -69,7 +80,7 @@ When updating an existing user, the password is optional, so that other
 fields on the user (such as their roles) may be updated without modifying
 the user's password.
 
-`password_hash` ::
+`password_hash`::
 (string) A _hash_ of the user's password. This must be produced using the
 same hashing algorithm as has been configured for password storage. For more
 details, see the explanation of the
@@ -82,17 +93,14 @@ performance and/or confidentiality reasons.
 The `password` parameter and the `password_hash` parameter cannot be
 used in the same request.
 
-`roles` (required)::
-(list) A set of roles the user has. The roles determine the user's access 
-permissions. To create a user without any roles, specify an empty list: `[]`.
-
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster privilege.
+`roles`::
+(Required, list) A set of roles the user has. The roles determine the user's
+access  permissions. To create a user without any roles, specify an empty list:
+`[]`.
 
 
-==== Examples
+[[security-api-put-user-example]]
+==== {api-examples-title}
 
 The following example creates a user `jacknich`:
 

x-pack/docs/en/rest-api/security/delete-app-privileges.asciidoc

@@ -8,24 +8,13 @@
 Removes 
 {stack-ov}/security-privileges.html#application-privileges[application privileges].
 
-==== Request
+[[security-api-delete-privilege-request]]
+==== {api-request-title}
 
 `DELETE /_security/privilege/<application>/<privilege>` 
 
-//==== Description
-
-==== Path Parameters
-
-`application` (required)::
-  (string) The name of the application. Application privileges are always
-  associated with exactly one application.
-
-`privilege` (required)::
-  (string) The name of the privilege.
-
-// ==== Request Body
-
-==== Authorization
+[[security-api-delete-privilege-prereqs]]
+==== {api-prereq-title}
 
 To use this API, you must have either:
 
@@ -33,7 +22,18 @@ To use this API, you must have either:
 - the _"Manage Application Privileges"_ global privilege for the application being referenced
   in the request
 
-==== Examples
+[[security-api-delete-privilege-path-params]]
+==== {api-path-parms-title}
+
+`application`::
+  (Required, string) The name of the application. Application privileges are
+  always associated with exactly one application.
+
+`privilege`::
+  (Required, string) The name of the privilege.
+
+[[security-api-delete-privilege-example]]
+==== {api-examples-title}
 
 The following example deletes the `read` application privilege from the 
 `myapp` application:

x-pack/docs/en/rest-api/security/delete-role-mappings.asciidoc

@@ -7,30 +7,33 @@
 
 Removes role mappings.
 
-==== Request
+[[security-api-delete-role-mapping-request]]
+==== {api-request-title}
 
 `DELETE /_security/role_mapping/<name>` 
 
-==== Description
+[[security-api-delete-role-mapping-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+[[security-api-delete-role-mapping-desc]]
+==== {api-description-title}
 
 Role mappings define which roles are assigned to each user. For more information, 
 see {stack-ov}/mapping-roles.html[Mapping users and groups to roles]. 
 
-==== Path Parameters
+[[security-api-delete-role-mapping-path-params]]
+==== {api-path-parms-title}
 
 `name`::
  (string) The distinct name that identifies the role mapping. The name is
   used solely as an identifier to facilitate interaction via the API; it does
   not affect the behavior of the mapping in any way.
 
-//==== Request Body
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster privilege.
-
 
-==== Examples
+[[security-api-delete-role-mapping-example]]
+==== {api-examples-title}
 
 The following example delete a role mapping:
 

x-pack/docs/en/rest-api/security/delete-roles.asciidoc

@@ -7,32 +7,34 @@
 
 Removes roles in the native realm.
 
-==== Request
+[[security-api-delete-role-request]]
+==== {api-request-title}
 
 `DELETE /_security/role/<name>` 
 
 
-==== Description
+[[security-api-delete-role-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+[[security-api-delete-role-desc]]
+==== {api-description-title}
 
 The Roles API is generally the preferred way to manage roles, rather than using
 file-based role management. For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
 
-==== Path Parameters
+[[security-api-delete-role-path-params]]
+==== {api-path-parms-title}
 
 `name`::
   (string) The name of the role. 
 
-//==== Request Body
-
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster
-privilege.
-
-
-==== Examples
+[[security-api-delete-role-example]]
+==== {api-examples-title}
 
 The following example deletes a `my_admin_role` role:
 

x-pack/docs/en/rest-api/security/delete-users.asciidoc

@@ -7,28 +7,31 @@
 
 Deletes users from the native realm. 
 
-==== Request
+[[security-api-delete-user-request]]
+==== {api-request-title}
 
 `DELETE /_security/user/<username>` 
 
-==== Description
+[[security-api-delete-user-prereqs]]
+==== {api-prereq-title}
 
-For more information about the native realm, see 
-{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
-
-==== Path Parameters
+* To use this API, you must have at least the `manage_security` cluster privilege.
 
-`username` (required)::
-  (string) An identifier for the user. 
+[[security-api-delete-user-desc]]
+==== {api-description-title}
 
-//==== Request Body
+For more information about the native realm, see 
+{stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
-==== Authorization
+[[security-api-delete-user-path-params]]
+==== {api-path-parms-title}
 
-To use this API, you must have at least the `manage_security` cluster privilege.
+`username`::
+  (Required, string) An identifier for the user. 
 
 
-==== Examples
+[[security-api-delete-user-example]]
+==== {api-examples-title}
 
 The following example deletes the user `jacknich`:
 

x-pack/docs/en/rest-api/security/disable-users.asciidoc

@@ -8,12 +8,19 @@
 Disables users in the native realm. 
 
 
-==== Request
+[[security-api-disable-user-request]]
+==== {api-request-title}
 
 `PUT /_security/user/<username>/_disable` 
 
 
-==== Description
+[[security-api-disable-user-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+[[security-api-disable-user-desc]]
+==== {api-description-title}
 
 By default, when you create users, they are enabled. You can use this API to 
 revoke a user's access to {es}. To re-enable a user, there is an 
@@ -22,19 +29,15 @@ revoke a user's access to {es}. To re-enable a user, there is an
 For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
-==== Path Parameters
-
-`username` (required)::
-  (string) An identifier for the user.
-
-//==== Request Body
-
-==== Authorization
+[[security-api-disable-user-path-params]]
+==== {api-path-parms-title}
 
-To use this API, you must have at least the `manage_security` cluster privilege.
+`username`::
+  (Required, string) An identifier for the user.
 
 
-==== Examples
+[[security-api-disable-user-example]]
+==== {api-examples-title}
 
 The following example disables the user `jacknich`:
 

x-pack/docs/en/rest-api/security/enable-users.asciidoc

@@ -8,12 +8,19 @@
 Enables users in the native realm. 
 
 
-==== Request
+[[security-api-enable-user-request]]
+==== {api-request-title}
 
 `PUT /_security/user/<username>/_enable` 
 
 
-==== Description
+[[security-api-enable-user-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+[[security-api-enable-user-desc]]
+==== {api-description-title}
 
 By default, when you create users, they are enabled. You can use this enable 
 users API and the <<security-api-disable-user,disable users API>> to change that attribute. 
@@ -21,19 +28,15 @@ users API and the <<security-api-disable-user,disable users API>> to change that
 For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
-==== Path Parameters
-
-`username` (required)::
-  (string) An identifier for the user.
-
-//==== Request Body
-
-==== Authorization
+[[security-api-enable-user-path-params]]
+==== {api-path-parms-title}
 
-To use this API, you must have at least the `manage_security` cluster privilege.
+`username`::
+  (Required, string) An identifier for the user.
 
 
-==== Examples
+[[security-api-enable-user-example]]
+==== {api-examples-title}
 
 The following example enables the user `jacknich`:
 

x-pack/docs/en/rest-api/security/get-api-keys.asciidoc

@@ -7,43 +7,48 @@
 
 Retrieves information for one or more API keys.
 
-==== Request
+[[security-api-get-api-key-request]]
+==== {api-request-title}
 
 `GET /_security/api_key`
 
-==== Description
+[[security-api-get-api-key-prereqs]]
+==== {api-prereq-title}
 
-The information for the API keys created by <<security-api-create-api-key,create API Key>> can be retrieved
-using this API.
+* To use this API, you must have at least the `manage_api_key` cluster privilege.
 
-==== Request Body
+[[security-api-get-api-key-desc]]
+==== {api-description-title}
+
+The information for the API keys created by
+<<security-api-create-api-key,create API Key>> can be retrieved using this API.
+
+[[security-api-get-api-key-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the query parameters of a GET request and
 pertain to retrieving api keys:
 
-`id` (optional)::
-(string) An API key id. This parameter cannot be used with any of `name`,
-`realm_name` or `username` are used.
+`id`::
+(Optional, string) An API key id. This parameter cannot be used with any of 
+`name`, `realm_name` or `username` are used.
 
-`name` (optional)::
-(string) An API key name. This parameter cannot be used with any of `id`,
-`realm_name` or `username` are used.
+`name`::
+(Optional, string) An API key name. This parameter cannot be used with any of
+`id`, `realm_name` or `username` are used.
 
-`realm_name` (optional)::
-(string) The name of an authentication realm. This parameter cannot be used with
-either `id` or `name`.
+`realm_name`::
+(Optional, string) The name of an authentication realm. This parameter cannot be
+used with either `id` or `name`.
 
-`username` (optional)::
-(string) The username of a user. This parameter cannot be used with either `id`
-or `name`.
+`username`::
+(Optional, string) The username of a user. This parameter cannot be used with
+either `id` or `name`.
 
 NOTE: While all parameters are optional, at least one of them is required.
 
-==== Authorization
-
-To use this API, you must have at least the `manage_api_key` cluster privilege.
-
-==== Examples
+[[security-api-get-api-key-example]]
+==== {api-examples-title}
 
 If you create an API key as follows:
 

x-pack/docs/en/rest-api/security/get-app-privileges.asciidoc

@@ -8,7 +8,8 @@
 Retrieves 
 {stack-ov}/security-privileges.html#application-privileges[application privileges].
 
-==== Request
+[[security-api-get-privileges-request]]
+==== {api-request-title}
 
 `GET /_security/privilege` +
 
@@ -17,35 +18,39 @@ Retrieves
 `GET /_security/privilege/<application>/<privilege>` 
 
 
-==== Description
+[[security-api-get-privileges-prereqs]]
+==== {api-prereq-title}
+
+To use this API, you must have either:
+
+- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
+- the _"Manage Application Privileges"_ global privilege for the application being referenced
+  in the request
+
+[[security-api-get-privileges-desc]]
+==== {api-description-title}
 
 To check a user's application privileges, use the
 <<security-api-has-privileges,has privileges API>>.
 
 
-==== Path Parameters
+[[security-api-get-privileges-path-params]]
+==== {api-path-parms-title}
 
 `application`::
-  (string) The name of the application. Application privileges are always
-  associated with exactly one application.
-  If you do not specify this parameter, the API returns information about all 
-  privileges for all applications.
+  (Optional, string) The name of the application. Application privileges are
+  always associated with exactly one application. If you do not specify this
+  parameter, the API returns information about all privileges for all
+  applications.
 
 `privilege`::
-  (string) The name of the privilege. If you do not specify this parameter, the 
-  API returns information about all privileges for the requested application.
+  (Optional, string) The name of the privilege. If you do not specify this
+  parameter, the API returns information about all privileges for the requested
+  application.
 
-//==== Request Body
-
-==== Authorization
-
-To use this API, you must have either:
-
-- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
-- the _"Manage Application Privileges"_ global privilege for the application being referenced
-  in the request
 
-==== Examples
+[[security-api-get-privileges-example]]
+==== {api-examples-title}
 
 The following example retrieves information about the `read` privilege for the 
 `app01` application:

x-pack/docs/en/rest-api/security/get-builtin-privileges.asciidoc

@@ -10,37 +10,44 @@ Retrieves the list of
 {stack-ov}/security-privileges.html#privileges-list-indices[index privileges] that are
 available in this version of {es}.
 
-==== Request
+[[security-api-get-builtin-privileges-request]]
+==== {api-request-title}
 
 `GET /_security/privilege/_builtin` 
 
 
-==== Description
+[[security-api-get-builtin-privileges-prereqs]]
+==== {api-prereq-title}
 
-This API retrieves the set of cluster and index privilege names that are available in the
-version of {es} that is being queried.
+* To use this API, you must have - the `manage_security` cluster privilege
+(or a greater privilege such as `all`).
+
+[[security-api-get-builtin-privileges-desc]]
+==== {api-description-title}
+
+This API retrieves the set of cluster and index privilege names that are
+available in the version of {es} that is being queried.
 
 To check whether a user has particular privileges, use the
 <<security-api-has-privileges,has privileges API>>.
 
-==== Results
+
+[[security-api-get-builtin-privileges-response-body]]
+==== {api-response-body-title}
 
 The response is an object with two fields:
 
 `cluster`:: (array of string) The list of
- {stack-ov}/security-privileges.html#privileges-list-cluster[cluster privileges] that are
- understood by this version of {es}
+ {stack-ov}/security-privileges.html#privileges-list-cluster[cluster privileges]
+ that are understood by this version of {es}
 
 `index`:: (array of string) The list of
- {stack-ov}/security-privileges.html#privileges-list-indices[index privileges] that are
- understood by this version of {es}
-
-==== Authorization
+ {stack-ov}/security-privileges.html#privileges-list-indices[index privileges]
+ that are understood by this version of {es}
 
-To use this API, you must have - the `manage_security` cluster privilege
-(or a greater privilege such as `all`)
 
-==== Examples
+[[security-api-get-builtin-privileges-example]]
+==== {api-examples-title}
 
 The following example retrieves the names of all builtin privileges:
 

x-pack/docs/en/rest-api/security/get-role-mappings.asciidoc

@@ -7,45 +7,51 @@
 
 Retrieves role mappings.
 
-==== Request
+[[security-api-get-role-mapping-request]]
+==== {api-request-title}
 
 `GET /_security/role_mapping` +
 
 `GET /_security/role_mapping/<name>` 
 
-==== Description
+[[security-api-get-role-mapping-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+[[security-api-get-role-mapping-desc]]
+==== {api-description-title}
 
 Role mappings define which roles are assigned to each user. For more information, 
 see {stack-ov}/mapping-roles.html[Mapping users and groups to roles]. 
 
-==== Path Parameters
+[[security-api-get-role-mapping-path-params]]
+==== {api-path-parms-title}
 
 `name`::
- (string) The distinct name that identifies the role mapping. The name is
-  used solely as an identifier to facilitate interaction via the API; it does
+  (Optional, string) The distinct name that identifies the role mapping. The name
+  is used solely as an identifier to facilitate interaction via the API; it does
   not affect the behavior of the mapping in any way. You can specify multiple 
   mapping names as a comma-separated list. If you do not specify this
   parameter, the API returns information about all role mappings. 
 
-//==== Request Body
-
-==== Results
+[[security-api-get-role-mapping-response-body]]
+==== {api-response-body-title}
 
 A successful call retrieves an object, where the keys are the
 names of the request mappings, and the values are the JSON representation of 
 those mappings. For more information, see 
 <<role-mapping-resources>>.
 
+[[security-api-get-role-mapping-response-codes]]
+==== {api-response-codes-title}
+
 If there is no mapping with the requested name, the
 response will have status code `404`.
 
 
-==== Authorization
-
-To use this API, you must have at least the `manage_security` cluster privilege.
-
-
-==== Examples
+[[security-api-get-role-mapping-example]]
+==== {api-examples-title}
 
 The following example retrieves information about the `mapping1` role mapping:
 

x-pack/docs/en/rest-api/security/get-roles.asciidoc

@@ -7,33 +7,46 @@
 
 Retrieves roles in the native realm.
 
-==== Request
+[[security-api-get-role-request]]
+==== {api-request-title}
 
 `GET /_security/role` +
 
 `GET /_security/role/<name>` +
 
-==== Description
+[[security-api-get-role-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster
+privilege.
+
+[[security-api-get-role-desc]]
+==== {api-description-title}
 
 For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
-==== Path Parameters
+[[security-api-get-role-path-params]]
+==== {api-path-parms-title}
 
 `name`::
-  (string) The name of the role. You can specify multiple roles as a 
+  (Optional, string) The name of the role. You can specify multiple roles as a 
   comma-separated list. If you do not specify this parameter, the API 
   returns information about all roles.
+  
+[[security-api-get-role-response-body]]
+==== {api-response-body-title}
 
-//==== Request Body
-
-==== Authorization
+A successful call returns an array of roles with the JSON representation of the
+role.
 
-To use this API, you must have at least the `manage_security` cluster
-privilege.
+[[security-api-get-role-response-codes]]
+==== {api-response-codes-title}
 
+If the role is not defined in the native realm, the request returns 404.
 
-==== Examples
+[[security-api-get-role-example]]
+==== {api-examples-title}
 
 The following example retrieves information about the `my_admin_role` role in 
 the native realm:
@@ -45,9 +58,6 @@ GET /_security/role/my_admin_role
 // CONSOLE
 // TEST[setup:admin_role]
 
-A successful call returns an array of roles with the JSON representation of the
-role. If the role is not defined in the native realm, the request returns 404.
-
 [source,js]
 --------------------------------------------------
 {
@@ -84,6 +94,3 @@ GET /_security/role
 // CONSOLE
 // TEST[continued]
 
-NOTE: If single role is requested, that role is returned as the response. When 
-requesting multiple roles, an object is returned holding the found roles, each 
-keyed by the relevant role name.

x-pack/docs/en/rest-api/security/get-tokens.asciidoc

@@ -7,11 +7,14 @@
 
 Creates a bearer token for access without requiring basic authentication.
 
-==== Request
+[[security-api-get-token-request]]
+==== {api-request-title}
 
 `POST /_security/oauth2/token` 
 
-==== Description
+
+[[security-api-get-token-desc]]
+==== {api-description-title}
 
 The tokens are created by the {es} Token Service, which is automatically enabled
 when you configure TLS on the HTTP interface. See <<tls-http>>. Alternatively,
@@ -35,7 +38,8 @@ If you want to invalidate a token immediately, you can do so by using the
 <<security-api-invalidate-token,invalidate token API>>.
 
 
-==== Request Body
+[[security-api-get-token-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of a POST request and
 pertain to creating a token:
@@ -71,7 +75,8 @@ supported grant type.
 grant type, this parameter is required. This parameter is not valid with any
 other supported grant type.
 
-==== Examples
+[[security-api-get-token-example]]
+==== {api-examples-title}
 
 The following example obtains a token using the `client_credentials` grant type,
 which simply creates a token as the authenticated user:

x-pack/docs/en/rest-api/security/get-users.asciidoc

@@ -8,31 +8,46 @@
 Retrieves information about users in the native realm and built-in users. 
 
 
-==== Request
+[[security-api-get-user-request]]
+==== {api-request-title}
 
 `GET /_security/user` +
 
 `GET /_security/user/<username>` 
 
-==== Description
+[[security-api-get-user-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_security` cluster privilege.
+
+
+[[security-api-get-user-desc]]
+==== {api-description-title}
 
 For more information about the native realm, see 
 {stack-ov}/realms.html[Realms] and <<configuring-native-realm>>. 
 
-==== Path Parameters
+[[security-api-get-user-path-params]]
+==== {api-path-parms-title}
 
 `username`::
-  (string) An identifier for the user. You can specify multiple usernames as a comma-separated list. If you omit this parameter, the API retrieves 
-  information about all users.
+  (Optional, string) An identifier for the user. You can specify multiple
+  usernames as a comma-separated list. If you omit this parameter, the API
+  retrieves information about all users.
 
-//==== Request Body
+[[security-api-get-user-response-body]]
+==== {api-response-body-title}
 
-==== Authorization
+A successful call returns an array of users with the JSON representation of the
+users. Note that user passwords are not included.
 
-To use this API, you must have at least the `manage_security` cluster privilege.
+[[security-api-get-user-response-codes]]
+==== {api-response-codes-title}
 
+If the user is not defined in the `native` realm, the request 404s.
 
-==== Examples
+[[security-api-get-user-example]]
+==== {api-examples-title}
 
 To retrieve a native user, submit a GET request to the `/_security/user/<username>`
 endpoint:
@@ -44,9 +59,6 @@ GET /_security/user/jacknich
 // CONSOLE
 // TEST[setup:jacknich_user]
 
-A successful call returns an array of users with the JSON representation of the
-user. Note that user passwords are not included.
-
 [source,js]
 --------------------------------------------------
 {  
@@ -65,8 +77,6 @@ user. Note that user passwords are not included.
 // CONSOLE
 // TESTRESPONSE
 
-If the user is not defined in the `native` realm, the request 404s.
-
 Omit the username to retrieve all users:
 
 [source,js]

x-pack/docs/en/rest-api/security/has-privileges.asciidoc

@@ -9,12 +9,22 @@
 The `has_privileges` API allows you to determine whether the logged in user has
 a specified list of privileges.
 
-==== Request
+[[security-api-has-privileges-request]]
+==== {api-request-title}
 
 `GET /_security/user/_has_privileges`
 
 
-==== Description
+[[security-api-has-privileges-prereqs]]
+==== {api-prereq-title}
+
+* All users can use this API, but only to determine their own privileges.
+To check the privileges of other users, you must use the run as feature. For
+more information, see
+{stack-ov}/run-as-privilege.html[Submitting requests on behalf of other users].
+
+[[security-api-has-privileges-desc]]
+==== {api-description-title}
 
 For a list of the privileges that you can specify in this API,
 see {stack-ov}/security-privileges.html[Security privileges].
@@ -22,8 +32,8 @@ see {stack-ov}/security-privileges.html[Security privileges].
 A successful call returns a JSON structure that shows whether each specified
 privilege is assigned to the user.
 
-
-==== Request Body
+[[security-api-has-privileges-request-body]]
+==== {api-request-body-title}
 
 `cluster`:: (list) A list of the cluster privileges that you want to check.
 
@@ -47,15 +57,9 @@ actions that are granted by those privileges
 `resources`::: (list) A list of resource names against which the privileges
 should be checked
 
-==== Authorization
-
-All users can use this API, but only to determine their own privileges.
-To check the privileges of other users, you must use the run as feature. For
-more information, see
-{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
-
 
-==== Examples
+[[security-api-has-privileges-example]]
+==== {api-examples-title}
 
 The following example checks whether the current user has a specific set of
 cluster, index, and application privileges:

x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc

@@ -7,43 +7,57 @@
 
 Invalidates one or more API keys.
 
-==== Request
+[[security-api-invalidate-api-key-request]]
+==== {api-request-title}
 
 `DELETE /_security/api_key`
 
-==== Description
+[[security-api-invalidate-api-key-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_api_key` cluster privilege.
+
+[[security-api-invalidate-api-key-desc]]
+==== {api-description-title}
 
 The API keys created by <<security-api-create-api-key,create API Key>> can be
 invalidated using this API.
 
-==== Request Body
+
+[[security-api-invalidate-api-key-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of a DELETE request and
 pertain to invalidating api keys:
 
-`id` (optional)::
-(string) An API key id. This parameter cannot be used with any of `name`,
-`realm_name` or `username` are used.
+`id`::
+(Optional, string) An API key id. This parameter cannot be used with any of
+`name`, `realm_name` or `username` are used.
 
-`name` (optional)::
-(string) An API key name. This parameter cannot be used with any of `id`,
-`realm_name` or `username` are used.
+`name`::
+(Optional, string) An API key name. This parameter cannot be used with any of
+`id`, `realm_name` or `username` are used.
 
-`realm_name` (optional)::
-(string) The name of an authentication realm. This parameter cannot be used with
-either `id` or `name`.
+`realm_name`::
+(Optional, string) The name of an authentication realm. This parameter cannot be
+used with either `id` or `name`.
 
-`username` (optional)::
-(string) The username of a user. This parameter cannot be used with either
-`id` or `name`.
+`username`::
+(Optional, string) The username of a user. This parameter cannot be used with
+either `id` or `name`.
 
 NOTE: While all parameters are optional, at least one of them is required.
 
-==== Authorization
+[[security-api-invalidate-api-key-response-body]]
+==== {api-response-body-title}
 
-To use this API, you must have at least the `manage_api_key` cluster privilege.
+A successful call returns a JSON structure that contains the ids of the API keys
+that were invalidated, the ids of the API keys that had already been invalidated,
+and potentially a list of errors encountered while invalidating specific api
+keys.
 
-==== Examples
+[[security-api-invalidate-api-key-example]]
+==== {api-examples-title}
 
 If you create an API key as follows:
 
@@ -71,7 +85,8 @@ API key information. For example:
 // TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
 // TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
 
-The following example invalidates the API key identified by specified `id` immediately:
+The following example invalidates the API key identified by specified `id`
+immediately:
 
 [source,js]
 --------------------------------------------------
@@ -84,7 +99,8 @@ DELETE /_security/api_key
 // TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
 // TEST[continued]
 
-The following example invalidates the API key identified by specified `name` immediately:
+The following example invalidates the API key identified by specified `name`
+immediately:
 
 [source,js]
 --------------------------------------------------
@@ -136,10 +152,6 @@ DELETE /_security/api_key
 // CONSOLE
 // TEST
 
-A successful call returns a JSON structure that contains the ids of the API keys that were invalidated, the ids
-of the API keys that had already been invalidated, and potentially a list of errors encountered while invalidating
-specific api keys.
-
 [source,js]
 --------------------------------------------------
 {
@@ -173,8 +185,8 @@ specific api keys.
 --------------------------------------------------
 // NOTCONSOLE
 
-<1> The ids of the API keys that were invalidated as part of this request.
-<2> The ids of the API keys that were already invalidated.
+<1> The IDs of the API keys that were invalidated as part of this request.
+<2> The IDs of the API keys that were already invalidated.
 <3> The number of errors that were encountered when invalidating the API keys.
 <4> Details about these errors. This field is not present in the response when
     `error_count` is 0.

x-pack/docs/en/rest-api/security/invalidate-tokens.asciidoc

@@ -7,11 +7,13 @@
 
 Invalidates one or more access tokens or refresh tokens.
 
-==== Request
+[[security-api-invalidate-token-request]]
+==== {api-request-title}
 
 `DELETE /_security/oauth2/token`
 
-==== Description
+[[security-api-invalidate-token-desc]]
+==== {api-description-title}
 
 The access tokens returned by the <<security-api-get-token,get token API>> have a
 finite period of time for which they are valid and after that time period, they 
@@ -25,34 +27,43 @@ only valid for 24 hours. They can also be used exactly once.
 If you want to invalidate one or more access or refresh tokens immediately, use
 this invalidate token API.
 
-
-==== Request Body
+[[security-api-invalidate-token-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of a DELETE request and
 pertain to invalidating tokens:
 
-`token` (optional)::
-(string) An access token. This parameter cannot be used any of `refresh_token`,
-`realm_name` or `username` are used.
+`token`::
+(Optional, string) An access token. This parameter cannot be used any of
+`refresh_token`, `realm_name` or `username` are used.
 
-`refresh_token` (optional)::
-(string) A refresh token. This parameter cannot be used any of `refresh_token`,
-`realm_name` or `username` are used.
+`refresh_token`::
+(Optional, string) A refresh token. This parameter cannot be used any of
+`refresh_token`, `realm_name` or `username` are used.
 
-`realm_name` (optional)::
-(string) The name of an authentication realm. This parameter cannot be used with
-either `refresh_token` or `token`.
+`realm_name`::
+(Optional, string) The name of an authentication realm. This parameter cannot be
+used with either `refresh_token` or `token`.
 
-`username` (optional)::
-(string) The username of a user. This parameter cannot be used with either
-`refresh_token` or `token`
+`username`::
+(Optional, string) The username of a user. This parameter cannot be used with
+either `refresh_token` or `token`
 
 NOTE: While all parameters are optional, at least one of them is required. More
 specifically, either one of `token` or `refresh_token` parameters is required.
 If none of these two are specified, then `realm_name` and/or `username` need to
 be specified.
 
-==== Examples
+
+[[security-api-invalidate-token-response-body]]
+==== {api-response-body-title}
+
+A successful call returns a JSON structure that contains the number of tokens
+that were invalidated, the number of tokens that had already been invalidated,
+and potentially a list of errors encountered while invalidating specific tokens.
+
+[[security-api-invalidate-token-example]]
+==== {api-examples-title}
 
 For example, if you create a token using the `client_credentials` grant type as
 follows:
@@ -178,10 +189,6 @@ DELETE /_security/oauth2/token
 // CONSOLE
 // TEST
 
-A successful call returns a JSON structure that contains the number of tokens
-that were invalidated, the number of tokens that had already been invalidated,
-and potentially a list of errors encountered while invalidating specific tokens.
-
 [source,js]
 --------------------------------------------------
 {

x-pack/docs/en/rest-api/security/oidc-authenticate-api.asciidoc

@@ -1,45 +1,61 @@
 [role="xpack"]
 [[security-api-oidc-authenticate]]
+=== OpenID Connect authenticate API
 
-=== OpenID Connect Authenticate API
+Submits the response to an oAuth 2.0 authentication request for consumption from
+{es}. Upon successful validation, {es} will respond with an {es} internal Access
+Token and Refresh Token that can be subsequently used for authentication.
 
-Submits the response to an oAuth 2.0 authentication request for consumption from {es}. Upon successful validation, {es}
-will respond with an {es} internal Access Token and Refresh Token that can be subsequently used for authentication. This
-API endpoint basically exchanges successful OpenID Connect Authentication responses for {es} access and refresh tokens
-to be used for authentication.
+[[security-api-oidc-authenticate-request]]
+==== {api-request-title}
 
-{es} exposes all the necessary OpenID Connect related functionality via the OpenID Connect APIs. These APIs
-are used internally by {kib} in order to provide OpenID Connect based authentication, but can also be used by other,
-custom web applications or other clients. See also
-<<security-api-oidc-prepare-authentication,OpenID Connect Prepare Authentication API>> and
-<<security-api-oidc-logout,OpenID Connect Logout API>>
+`POST /_security/oidc/authenticate`
 
-==== Request
+//[[security-api-oidc-authenticate-prereqs]]
+//==== {api-prereq-title}
 
-`POST /_security/oidc/authenticate`
+[[security-api-oidc-authenticate-desc]]
+==== {api-description-title}
+
+This API endpoint basically exchanges successful OpenID Connect Authentication
+responses for {es} access and refresh tokens to be used for authentication.
 
-==== Request Body
+{es} exposes all the necessary OpenID Connect related functionality via the
+OpenID Connect APIs. These APIs are used internally by {kib} in order to provide
+OpenID Connect based authentication, but can also be used by other, custom web
+ applications or other clients. See also
+<<security-api-oidc-prepare-authentication,OpenID Connect prepare authentication API>>
+and <<security-api-oidc-logout,OpenID Connect logout API>>
+
+[[security-api-oidc-authenticate-request-body]]
+==== {api-request-body-title}
 
 `redirect_uri`::
-The URL to which the OpenID Connect Provider redirected the User Agent in response to an authentication request, after a
- successful authentication. This URL is expected to be provided as-is (URL encoded), taken from the body of the response
- or as the value of a `Location` header in the response from the OpenID Connect Provider.
+The URL to which the OpenID Connect Provider redirected the User Agent in
+response to an authentication request, after a successful authentication. This
+URL is expected to be provided as-is (URL encoded), taken from the body of the
+response or as the value of a `Location` header in the response from the OpenID
+Connect Provider.
 
 `state`::
-String value used to maintain state between the authentication request and the response. This value needs to be the same
-as the one that was provided to the call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
+String value used to maintain state between the authentication request and the
+response. This value needs to be the same as the one that was provided to the
+call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
 and included in the response to that call.
 
 `nonce`::
-String value used to associate a Client session with an ID Token, and to mitigate replay attacks. This value needs to be
-the same as the one that was provided to the call to `/_security/oidc/prepare` earlier, or the one that was generated by {es}
-and included in the response to that call.
+String value used to associate a Client session with an ID Token and to mitigate
+replay attacks. This value needs to be the same as the one that was provided to
+the call to `/_security/oidc/prepare` earlier, or the one that was generated by
+{es} and included in the response to that call.
 
-==== Examples
+[[security-api-oidc-authenticate-example]]
+==== {api-examples-title}
 
-The following example request exchanges the response that was returned from the OpenID Connect Provider after a successful
-authentication, for an {es} access token and refresh token to be used in subsequent requests. This example is from an
-authentication that uses the authorization code grant flow.
+The following example request exchanges the response that was returned from the
+OpenID Connect Provider after a successful authentication, for an {es} access
+token and refresh token to be used in subsequent requests. This example is from 
+an authentication that uses the authorization code grant flow.
 
 [source,js]
 --------------------------------------------------
@@ -53,8 +69,9 @@ POST /_security/oidc/authenticate
 // CONSOLE
 // TEST[catch:unauthorized]
 
-The following example output contains the access token that was generated in response, the amount of time (in
-seconds) that the token expires in, the type, and the refresh token:
+The following example output contains the access token that was generated in
+response, the amount of time (in seconds) that the token expires in, the type,
+and the refresh token:
 
 [source,js]
 --------------------------------------------------

x-pack/docs/en/rest-api/security/oidc-logout-api.asciidoc

@@ -1,32 +1,42 @@
 [role="xpack"]
 [[security-api-oidc-logout]]
+=== OpenID Connect logout API
 
-=== OpenID Connect Logout API
+Submits a request to invalidate a refresh token and an access token that was
+generated as a response to a call to `/_security/oidc/authenticate`. 
 
-Submits a request to invalidate a refresh token and an access token that was generated as a response to a call to
-`/_security/oidc/authenticate`. If the OpenID Connect authentication realm in {es} is accordingly configured, the
-response to this call will contain a URI pointing to the End Session Endpoint of the OpenID Connect Provider in
-order to perform Single Logout
+[[security-api-oidc-logout-request]]
+==== {api-request-title}
 
-{es} exposes all the necessary OpenID Connect related functionality via the OpenID Connect APIs. These APIs
-are used internally by {kib} in order to provide OpenID Connect based authentication, but can also be used by other,
-custom web applications or other clients. See also <<security-api-oidc-authenticate,OpenID Connect Authenticate API>>
-and <<security-api-oidc-prepare-authentication,OpenID Connect Prepare Authentication API>>
+`POST /_security/oidc/logout`
 
-==== Request
+[[security-api-oidc-logout-desc]]
+==== {api-description-title}
 
-`POST /_security/oidc/logout`
+If the OpenID Connect authentication realm in {es} is accordingly configured,
+the response to this call will contain a URI pointing to the End Session
+Endpoint of the OpenID Connect Provider in order to perform Single Logout.
+
+{es} exposes all the necessary OpenID Connect related functionality via the
+OpenID Connect APIs. These APIs are used internally by {kib} in order to provide
+OpenID Connect based authentication, but can also be used by other, custom web
+applications or other clients. See also
+<<security-api-oidc-authenticate,OpenID Connect authenticate API>>
+and
+<<security-api-oidc-prepare-authentication,OpenID Connect prepare authentication API>>.
 
-==== Request Body
+[[security-api-oidc-logout-request-body]]
+==== {api-request-body-title}
 
 `access_token`::
 The value of the access token to be invalidated as part of the logout.
 
 `refresh_token`::
-The value of the refresh token to be invalidated as part of the logout. (Optional)
+(Optional) The value of the refresh token to be invalidated as part of the logout.
 
 
-==== Examples
+[[security-api-oidc-logout-example]]
+==== {api-examples-title}
 
 The following example performs logout
 
@@ -41,8 +51,9 @@ POST /_security/oidc/logout
 // CONSOLE
 // TEST[catch:unauthorized]
 
-The following example output of the response contains the URI pointing to the End Session Endpoint of the
-OpenID Connect Provider with all the parameters of the Logout Request, as HTTP GET parameters
+The following example output of the response contains the URI pointing to the
+End Session Endpoint of the OpenID Connect Provider with all the parameters of
+the Logout Request, as HTTP GET parameters:
 
 [source,js]
 --------------------------------------------------

x-pack/docs/en/rest-api/security/oidc-prepare-authentication-api.asciidoc

@@ -1,53 +1,69 @@
 [role="xpack"]
 [[security-api-oidc-prepare-authentication]]
-
 === OpenID Connect Prepare Authentication API
 
-Creates an oAuth 2.0 authentication request as a URL string based on the configuration of the respective
-OpenID Connect authentication realm in {es}. The response of this API is a URL pointing to the Authorization Endpoint
-of the configured OpenID Connect Provider and can be used to redirect the browser of the user in order to continue
-the authentication process.
-
-{es} exposes all the necessary OpenID Connect related functionality via the OpenID Connect APIs. These APIs
-are used internally by {kib} in order to provide OpenID Connect based authentication, but can also be used by other,
-custom web applications or other clients. See also <<security-api-oidc-authenticate,OpenID Connect Authenticate API>>
-and <<security-api-oidc-logout,OpenID Connect Logout API>>
+Creates an oAuth 2.0 authentication request as a URL string based on the
+configuration of the respective OpenID Connect authentication realm in {es}. 
 
-==== Request
+[[security-api-oidc-prepare-authentication-request]]
+==== {api-request-title}
 
 `POST /_security/oidc/prepare`
 
+//[[security-api-oidc-prepare-authentication-prereqs]]
+//==== {api-prereq-title}
+
+[[security-api-oidc-prepare-authentication-desc]]
+==== {api-description-title}
+
+The response of this API is a URL pointing to the Authorization Endpoint of the 
+configured OpenID Connect Provider and can be used to redirect the browser of 
+the user in order to continue the authentication process.
 
-==== Request Body
+{es} exposes all the necessary OpenID Connect related functionality via the
+OpenID Connect APIs. These APIs are used internally by {kib} in order to provide
+OpenID Connect based authentication, but can also be used by other, custom web 
+applications or other clients. See also
+<<security-api-oidc-authenticate,OpenID Connect authenticate API>>
+and <<security-api-oidc-logout,OpenID Connect logout API>>.
+
+[[security-api-oidc-prepare-authentication-request-body]]
+==== {api-request-body-title}
 
 The following parameters can be specified in the body of the request:
 
 `realm`::
-The name of the OpenID Connect realm in {es} the configuration of which should be used in order to
-generate the authentication request. Cannot be specified when `iss` is specified.
+The name of the OpenID Connect realm in {es} the configuration of which should 
+be used in order to generate the authentication request. Cannot be specified
+when `iss` is specified.
 
 `state`::
-String value used to maintain state between the authentication request and the response, typically used
-as a Cross-Site Request Forgery mitigation. If the caller of the API doesn't provide a value, {es} will
-generate one with sufficient entropy itself and return it in the response.
+String value used to maintain state between the authentication request and the
+response, typically used as a Cross-Site Request Forgery mitigation. If the
+caller of the API doesn't provide a value, {es} will generate one with
+sufficient entropy itself and return it in the response.
 
 `nonce`::
-String value used to associate a Client session with an ID Token, and to mitigate replay attacks.
-If the caller of the API doesn't provide a value, {es} will generate one with sufficient entropy itself
-and return it in the response.
+String value used to associate a Client session with an ID Token and to mitigate
+replay attacks. If the caller of the API doesn't provide a value, {es} will
+generate one with sufficient entropy itself and return it in the response.
 
 `issuer`::
-In the case of a 3rd Party initiated Single Sign On, this is the Issuer Identifier for the OP that the RP is
-to send the Authentication Request to. Cannot be specified when `realm` is specified.
+In the case of a 3rd Party initiated Single Sign On, this is the Issuer
+Identifier for the OP that the RP is to send the Authentication Request to.
+Cannot be specified when `realm` is specified.
 
 `login_hint`::
-In the case of a 3rd Party initiated Single Sign On, a string value to be included in the authentication
-request, as the `login_hint` parameter. This parameter is not valid when `realm` is specified
+In the case of a 3rd Party initiated Single Sign On, a string value to be
+included in the authentication request, as the `login_hint` parameter. This
+parameter is not valid when `realm` is specified
 
 
-==== Examples
+[[security-api-oidc-prepare-authentication-example]]
+==== {api-examples-title}
 
-The following example generates an authentication request for the OpenID Connect Realm `oidc1`
+The following example generates an authentication request for the OpenID Connect
+Realm `oidc1`:
 
 [source,js]
 --------------------------------------------------
@@ -57,8 +73,9 @@ POST /_security/oidc/prepare
 }
 --------------------------------------------------
 // CONSOLE
-The following example output of the response contains the URI pointing to the Authorization Endpoint of the
-OpenID Connect Provider with all the parameters of the Authentication Request, as HTTP GET parameters
+
+The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
+the Authentication Request, as HTTP GET parameters:
 
 [source,js]
 --------------------------------------------------
@@ -71,8 +88,9 @@ OpenID Connect Provider with all the parameters of the Authentication Request, a
 // TESTRESPONSE[s/4dbrihtIAt3wBTwo6DxK-vdk-sSyDBV8Yf0AjdkdT5I/\$\{body.state\}/]
 // TESTRESPONSE[s/WaBPH0KqPVdG5HHdSxPRjfoZbXMCicm5v1OiAj0DUFM/\$\{body.nonce\}/]
 
-The following example generates an authentication request for the OpenID Connect Realm `oidc1`, where the
-values for the state and the nonce have been generated by the client
+The following example generates an authentication request for the OpenID Connect
+Realm `oidc1`, where the values for the state and the nonce have been generated
+by the client:
 
 [source,js]
 --------------------------------------------------
@@ -85,8 +103,8 @@ POST /_security/oidc/prepare
 --------------------------------------------------
 // CONSOLE
 
-The following example output of the response contains the URI pointing to the Authorization Endpoint of the
-OpenID Connect Provider with all the parameters of the Authentication Request, as HTTP GET parameters
+The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
+the Authentication Request, as HTTP GET parameters:
 
 [source,js]
 --------------------------------------------------
@@ -98,8 +116,9 @@ OpenID Connect Provider with all the parameters of the Authentication Request, a
 --------------------------------------------------
 // TESTRESPONSE
 
-The following example generates an authentication request for a 3rd party initiated single sign on, specifying the
-issuer that should be used for matching the appropriate OpenID Connect Authentication realm
+The following example generates an authentication request for a 3rd party
+initiated single sign on, specifying the issuer that should be used for matching
+the appropriate OpenID Connect Authentication realm:
 
 [source,js]
 --------------------------------------------------
@@ -111,8 +130,8 @@ POST /_security/oidc/prepare
 --------------------------------------------------
 // CONSOLE
 
-The following example output of the response contains the URI pointing to the Authorization Endpoint of the
-OpenID Connect Provider with all the parameters of the Authentication Request, as HTTP GET parameters
+The following example output of the response contains the URI pointing to the Authorization Endpoint of the OpenID Connect Provider with all the parameters of
+the Authentication Request, as HTTP GET parameters:
 
 [source,js]
 --------------------------------------------------

x-pack/docs/en/rest-api/security/put-app-privileges.asciidoc

@@ -8,14 +8,25 @@
 Adds or updates 
 {stack-ov}/security-privileges.html#application-privileges[application privileges].
 
-==== Request
+[[security-api-put-privileges-request]]
+==== {api-request-title}
 
 `POST /_security/privilege` +
 
 `PUT /_security/privilege`
 
 
-==== Description
+[[security-api-put-privileges-prereqs]]
+==== {api-prereq-title}
+
+To use this API, you must have either:
+
+- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
+- the _"Manage Application Privileges"_ global privilege for the application 
+being referenced in the request
+
+[[security-api-put-privileges-desc]]
+==== {api-description-title}
 
 This API creates or updates privileges. To remove privileges, use the 
 <<security-api-delete-privilege,delete application privilege API>>. 
@@ -26,7 +37,8 @@ For more information, see
 To check a user's application privileges, use the
 <<security-api-has-privileges,has privileges API>>.
 
-==== Request Body
+[[security-api-put-privileges-request-body]]
+==== {api-request-body-title}
 
 The body is a JSON object where the names of the fields are the application
 names and the value of each field is an object. The fields in this inner
@@ -43,7 +55,7 @@ that begin with `_` are reserved for system usage.
 [[security-api-app-privileges-validation]]
 ==== Validation
 
-Application Names::
+Application names::
     Application names are formed from a _prefix_, with an optional _suffix_ that
     conform to the following rules:
     * The prefix must begin with a lowercase ASCII letter
@@ -54,23 +66,22 @@ Application Names::
       `\\`, `/`, `*`, `?`, `"`, `<`, `>`, `|`, `,`, `*`
     * No part of the name can contain whitespace.
 
-Privilege Names::
+Privilege names::
     Privilege names must begin with a lowercase ASCII letter and must contain
     only ASCII letters and digits along with the characters `_`, `-` and `.`
 
-Action Names::
+Action names::
     Action names can contain any number of printable ASCII characters and must 
     contain at least one of the following characters: `/` `*`, `:`
 
-==== Authorization
-
-To use this API, you must have either:
+[[security-api-put-privileges-response-body]]
+==== {api-response-body-title}
 
-- the `manage_security` cluster privilege (or a greater privilege such as `all`); _or_
-- the _"Manage Application Privileges"_ global privilege for the application being referenced
-  in the request
+A successful call returns a JSON structure that shows whether the privilege has
+been created or updated.
 
-==== Examples
+[[security-api-put-privileges-example]]
+==== {api-examples-title}
 
 To add a single privilege, submit a PUT or POST request to the
 `/_security/privilege/<application>/<privilege>` endpoint. For example:
@@ -102,9 +113,6 @@ PUT /_security/privilege
     wildcard and returns `true`.
 <3> The metadata object is optional.
 
-A successful call returns a JSON structure that shows whether the privilege has
-been created or updated.
-
 [source,js]
 --------------------------------------------------
 {

x-pack/docs/en/rest-api/security/ssl.asciidoc

@@ -8,12 +8,21 @@
 The `certificates` API enables you to retrieve information about the X.509
 certificates that are used to encrypt communications in your {es} cluster.
 
-==== Request
+[[security-api-ssl-request]]
+==== {api-request-title}
 
 `GET /_ssl/certificates`
 
 
-==== Description
+[[security-api-ssl-prereqs]]
+==== {api-prereq-title}
+
+* If the {security-features} are enabled, you must have `monitor` cluster
+privileges to use this API. For more information, see
+{stack-ov}/security-privileges.html[Security privileges].
+
+[[security-api-ssl-desc]]
+==== {api-description-title}
 
 For more information about how certificates are configured in conjunction with
 Transport Layer Security (TLS), see
@@ -45,8 +54,8 @@ If {es} is configured to use a keystore or truststore, the API output
 includes all certificates in that store, even though some of the certificates
 might not be in active use within the cluster.
 
-
-==== Results
+[[security-api-ssl-response-body]]
+==== {api-response-body-title}
 
 The response is an array of objects, with each object representing a
 single certificate. The fields in each object are:
@@ -64,14 +73,9 @@ certificate, this field has a value of `true`.
 `expiry`:: (string) The ISO formatted date of the certificate's expiry
 (not-after) date.
 
-==== Authorization
-
-If the {security-features} are enabled, you must have `monitor` cluster
-privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
-
 
-==== Examples
+[[security-api-ssl-example]]
+==== {api-examples-title}
 
 The following example provides information about the certificates on a single
 node of {es}: