[DOCS] Format tokens API (elastic/x-pack-elasticsearch#2578)

* [DOCS] Format tokens API

* [DOCS] Cleaned up tokens API comment

Original commit: elastic/x-pack-elasticsearch@f818367c68

docs/en/rest-api/security/tokens.asciidoc

@@ -3,10 +3,54 @@
 === Token Management APIs
 
 The `token` API enables you to create and invalidate bearer tokens for access
-without requiring basic authentication. The get token API takes the same
+without requiring basic authentication.
-parameters as a typical OAuth 2.0 token API except for the use of a JSON
-request body.
 
+==== Request
+
+`POST /_xpack/security/oauth2/token` +
+
+`DELETE /_xpack/security/oauth2/token`
+
+==== Description
+
+The Get Token API takes the same parameters as a typical OAuth 2.0 token API
+except for the use of a JSON request body.
+
+A successful Get Token API call returns a JSON structure that contains the access
+token, the amount of time (seconds) that the token expires in, the type, and the
+scope if available.
+
+The tokens returned by the Get Token API have a finite period of time for which
+they are valid and after that time period, they can no longer be used. However,
+if you want to invalidate a token immediately, you can do so by using the Delete
+Token API.
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a POST request and
+pertain to creating a token:
+
+`grant_type`::
+(string) The type of grant. Currently only the `password` grant type is supported.
+
+`password` (required)::
+(string) The user's password.
+
+`scope`::
+(string) The scope of the token. Currently tokens are only issued for a scope of
+`FULL` regardless of the value sent with the request.
+
+`username` (required)::
+(string) The username that identifies the user.
+
+The following parameters can be specified in the body of a DELETE request and
+pertain to deleting a token:
+
+`token`::
+(string) An access token.
+
+==== Examples
 [[security-api-get-token]]
 To obtain a token, submit a POST request to the `/_xpack/security/oauth2/token`
 endpoint.
@@ -22,22 +66,8 @@ POST /_xpack/security/oauth2/token
 --------------------------------------------------
 // CONSOLE
 
-.Token Request Fields
+The following example output contains the access token, the amount of time (in
-[cols="4,^2,10"]
+seconds) that the token expires in, and the type:
-|=======================
-| Name        | Required  | Description
-| `username`  | yes       | The username that identifies the user.
-| `password`  | yes       | The user's password.
-| `grant_type`| yes       | The type of grant. Currently only the `password`
-                            grant type is supported.
-| `scope`     | no        | The scope of the token. Currently tokens are only
-                            issued for a scope of `FULL` regardless of the value
-                            sent with the request.
-|=======================
-
-A successful call returns a JSON structure that contains the access token, the
-amount of time (seconds) that the token expires in, the type, and the scope if
-available.
 
 [source,js]
 --------------------------------------------------
@@ -49,9 +79,6 @@ available.
 --------------------------------------------------
 // TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
 
-A successful call returns a JSON structure that shows whether the user has been
-created or updated.
-
 The token returned by this API can be used by sending a request with a
 `Authorization` header with a value having the prefix `Bearer ` followed
 by the value of the `access_token`.
@@ -62,10 +89,8 @@ curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvb
 --------------------------------------------------
 
 [[security-api-invalidate-token]]
-The tokens returned from this API have a finite period of time for which they
+If a token must be invalidated immediately, you can do so by submitting a DELETE
-are valid and after that time period, they can no longer be used. However, if
+request to `/_xpack/security/oauth2/token`.  For example:
-a token must be invalidated immediately, you can do so by submitting a DELETE
-request to `/_xpack/security/oauth2/token`.
 
 [source,js]
 --------------------------------------------------