[DOCS] Format the authenticate API (elastic/x-pack-elasticsearch#2572)
Original commit: elastic/x-pack-elasticsearch@7e25f952370471a826ae62ba968471c77732605c
The Authenticate API enables you to submit a request with a basic auth header to
authenticate a user and retrieve information about the authenticated user.
-Returns a 401 status code if the user cannot be authenticated.
-To authenticate a user, submit a GET request to the `_xpack/security/_authenticate` endpoint:
+
+==== Request
+
+`GET _xpack/security/_authenticate`
+
+
+==== Description
+
+A successful call returns a JSON structure that shows what roles are assigned
+to the user as well as any assigned metadata.
+
+If the user cannot be authenticated, this API returns a 401 status code.
+
+==== Examples
+
+To authenticate a user, submit a GET request to the
+`_xpack/security/_authenticate` endpoint:
[source,js]
--------------------------------------------------
@@ -14,8 +29,7 @@ GET _xpack/security/_authenticate
--------------------------------------------------
// CONSOLE
-A successful call returns a JSON structure that shows what roles are assigned
-to the user as well as any assigned metadata.
+The following example output provides information about the "rdeniro" user:
[source,js]
--------------------------------------------------
