[DOCS] Updates for API usage (#51989) (#53147)

* [DOCS] Updates for API usage

* Changes from Larry

* Update docs/api/using-api.asciidoc

Co-Authored-By: Larry Gregory <lgregorydev@gmail.com>

* Comments from Larry

* Comment from Larry

docs/api/spaces-management/post.asciidoc

@@ -16,28 +16,28 @@ experimental["The underlying Spaces concepts are stable, but the APIs for managi
 [[spaces-api-post-request-body]]
 ==== Request body
 
-`id`:: 
+`id`::
   (Required, string) The space ID that is part of the Kibana URL when inside the space. You are unable to change the ID with the update operation.
 
-`name`:: 
+`name`::
   (Required, string) The display name for the space.
 
-`description`:: 
+`description`::
   (Optional, string) The description for the space.
 
-`disabledFeatures`:: 
+`disabledFeatures`::
   (Optional, string array) The list of disabled features for the space. To get a list of available feature IDs, use the <<features-api-get, Features API>>.
 
-`initials`:: 
+`initials`::
   (Optional, string) Specifies the initials shown in the space avatar. By default, the initials are automatically generated from the space name. Initials must be 1 or 2 characters.
 
-`color`:: 
+`color`::
   (Optional, string) Specifies the hexadecimal color code used in the space avatar. By default, the color is automatically generated from the space name.
 
-`imageUrl`:: 
+`imageUrl`::
   (Optional, string) Specifies the data-url encoded image to display in the space avatar. If specified, `initials` will not be displayed, and the `color` will be visible as the background color for transparent images.
   For best results, your image should be 64x64. Images will not be optimized by this API call, so care should be taken when using custom images.
-  
+
 [[spaces-api-post-response-codes]]
 ==== Response codes
 

docs/api/using-api.asciidoc

@@ -1,7 +1,7 @@
 [[using-api]]
 == Using the APIs
 
-Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols. 
+Interact with the {kib} APIs through the `curl` command and HTTP and HTTPs protocols.
 
 It is recommended that you use HTTPs on port 5601 because it is more secure.
 
@@ -34,13 +34,37 @@ For example, the following `curl` command exports a dashboard:
 curl -X POST -u $USER:$PASSWORD "localhost:5601/api/kibana/dashboards/export?dashboard=942dcef0-b2cd-11e8-ad8e-85441f0c2e5c"
 --
 
-The following {kib} APIs are available:
+[float]
+[[api-request-headers]]
+=== Request headers
 
-* <<features-api-get, Get features API>>
-* <<spaces-api, Kibana spaces API>>
-* <<role-management-api, Kibana role management APIs>>
-* <<saved-objects-api, Saved objects APIs>>
-* <<dashboard-api, Import and export dashboards APIs>>
-* <<logstash-configuration-management-api, Logstash configuration mangaement APIs>>
-* <<url-shortening-api, Shorten URL API>>
-* <<upgrade-assistant-api, Upgrade assistant APIs>>
+For all APIs, you must use a request header. The {kib} APIs support the `kbn-xsrf` and `Content-Type` headers.
+
+`kbn-xsrf: true`::
+  By default, you must use `kbn-xsrf` for all API calls, except in the following scenarios:
+
+* The API endpoint uses the `GET` or `HEAD` methods
+
+* The path is whitelisted using the <<settings, `server.xsrf.whitelist`>> setting
+
+* XSRF protections are disabled using the `server.xsrf.disableProtection` setting
+
+`Content-Type: application/json`::
+  Applicable only when you send a payload in the API request. {kib} API requests and responses use JSON. Typically, if you include the `kbn-xsrf` header, you must also include the `Content-Type` header. 
+
+Request header example:
+
+[source,sh]
+--
+curl -X POST \
+  http://localhost:5601/api/spaces/space \
+  -H 'Content-Type: application/json' \
+  -H 'kbn-xsrf: true' \
+  -d '{
+	"id": "sales",
+	"name": "Sales",
+	"description": "This is your Sales Space!",
+	"disabledFeatures": []
+}
+'
+--

docs/setup/settings.asciidoc

@@ -358,6 +358,18 @@ all http requests to https over the port configured as `server.port`.
 `server.ssl.supportedProtocols:`:: *Default: TLSv1.1, TLSv1.2*  An array of
 supported protocols with versions. Valid protocols: `TLSv1`, `TLSv1.1`, `TLSv1.2`
 
+`server.xsrf.whitelist:`:: It is not recommended to disable protections for
+arbitrary API endpoints. Instead, supply the `kbn-xsrf` header. There are some
+scenarios where whitelisting is required, however, such as
+<<kibana-authentication, SAML and OpenID Connect Single Sign-On setups>>.
+The `server.xsrf.whitelist` setting requires the following format:
+
+[source,text]
+
+----
+*Default: [ ]* An array of API endpoints which should be exempt from Cross-Site Request Forgery ("XSRF") protections.
+----
+
 `status.allowAnonymous:`:: *Default: false* If authentication is enabled,
 setting this to `true` enables unauthenticated users to access the Kibana server
 status API and status page.