diff --git a/docs/reference/rest-api/security.asciidoc b/docs/reference/rest-api/security.asciidoc
index 94b632490ad86..e5c42a93d34b1 100644
--- a/docs/reference/rest-api/security.asciidoc
+++ b/docs/reference/rest-api/security.asciidoc
@@ -12,6 +12,8 @@ Use the following APIs to perform security activities.
 * <<security-api-has-privileges>>
 * <<security-api-ssl>>
 * <<security-api-get-builtin-privileges>>
+* <<security-api-get-settings>>
+* <<security-api-update-settings>>
 * <<security-api-get-user-privileges>>
 
 [discrete]
diff --git a/docs/reference/rest-api/security/get-settings.asciidoc b/docs/reference/rest-api/security/get-settings.asciidoc
index 5c38b96903cbd..3a4fec395cbc7 100644
--- a/docs/reference/rest-api/security/get-settings.asciidoc
+++ b/docs/reference/rest-api/security/get-settings.asciidoc
@@ -5,6 +5,8 @@
 <titleabbrev>Get Security settings</titleabbrev>
 ++++
 
+Retrieves settings for the security internal index.
+
 [[security-api-get-settings-prereqs]]
 ==== {api-prereq-title}
 
@@ -14,11 +16,16 @@
 ==== {api-description-title}
 This API allows a user to retrieve the user-configurable settings for the 
 Security internal index (`.security` and associated indices). Only a subset of 
-the index settings — those that are user-configurable—will be shown. This includes:
+the index settings — those that are user-configurable—will be shown. This
+includes:
 
 - `index.auto_expand_replicas`
 - `index.number_of_replicas`
 
+
+[[security-api-get-settings-example]]
+==== {api-examples-title}
+
 An example of retrieving the security settings:
 
 [source,console]
diff --git a/docs/reference/rest-api/security/update-settings.asciidoc b/docs/reference/rest-api/security/update-settings.asciidoc
index 0ea41d86e85ed..652b722b0af48 100644
--- a/docs/reference/rest-api/security/update-settings.asciidoc
+++ b/docs/reference/rest-api/security/update-settings.asciidoc
@@ -5,11 +5,31 @@
 <titleabbrev>Update Security settings</titleabbrev>
 ++++
 
+Updates the settings of the security internal indices.
+
+
 [[security-api-update-settings-prereqs]]
 ==== {api-prereq-title}
 
 * To use this API, you must have at least the `manage_security` cluster privilege.
 
+
+[[security-api-update-settings-request-body]]
+==== {api-request-body-title}
+
+`security`::
+(Optional, object) Settings to be used for the index used for most security 
+configuration, including Native realm users and roles configured via the API.
+
+`security-tokens`::
+(Optional, object) Settings to be used for the index used to store 
+<<security-api-get-token,tokens>>.
+
+`security`::
+(Optional, object) Settings to be used for the index used to store 
+<<security-api-activate-user-profile, profile>> information.
+
+
 [[security-api-update-settings-desc]]
 ==== {api-description-title}
 This API allows a user to modify the settings for the Security internal indices 
@@ -19,6 +39,10 @@ be modified. This includes:
 - `index.auto_expand_replicas`
 - `index.number_of_replicas`
 
+
+[[security-api-update-settings-example]]
+==== {api-examples-title}
+
 An example of modifying the Security settings:
 
 [source,console]
@@ -43,18 +67,3 @@ The configured settings can be retrieved using the
 is not in use on the system, but settings are provided for it, the request will 
 be rejected - this API does not yet support configuring the settings for these 
 indices before they are in use.
-
-
-==== {api-request-body-title}
-
-`security`::
-(Optional, object) Settings to be used for the index used for most security 
-configuration, including Native realm users and roles configured via the API.
-
-`security-tokens`::
-(Optional, object) Settings to be used for the index used to store 
-<<security-api-get-token,tokens>>.
-
-`security`::
-(Optional, object) Settings to be used for the index used to store 
-<<security-api-activate-user-profile, profile>> information.