diff --git a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc
index 7a9972bbaeb5e..c4b7c734a06ce 100644
--- a/x-pack/docs/en/rest-api/security/get-tokens.asciidoc
+++ b/x-pack/docs/en/rest-api/security/get-tokens.asciidoc
@@ -12,6 +12,10 @@ Creates a bearer token for access without requiring basic authentication.
 
 `POST /_security/oauth2/token` 
 
+[[security-api-get-token-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have the `manage_token` cluster privilege.
 
 [[security-api-get-token-desc]]
 ==== {api-description-title}
@@ -45,33 +49,56 @@ 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. Supported grant types are: `password`, `_kerberos`,
-`client_credentials` and `refresh_token`. The `_kerberos` grant type
-is supported internally and implements SPNEGO based Kerberos support. The `_kerberos`
-grant type may change from version to version.
+(Required, string) The type of grant.
+Supported grant types are: `password`, `_kerberos`,
+`client_credentials` and `refresh_token`.
+
+`client_credentials`:::
+This grant type implements the Client Credentials Grant of OAuth2. It is geared
+for machine to machine communication and is not suitable or designed for the
+self-service user creation of tokens. It generates only access tokens that
+cannot be refreshed. The premise is that the entity that uses
+`client_credentials` has constant access to a set of (client, not end-user)
+credentials and can authenticate itself at will. 
+
+`_kerberos`::: 
+This grant type is supported internally and implements SPNEGO based Kerberos
+support. The `_kerberos` grant type may change from version to version.
+
+`password`:::
+This grant type implements the Resource Owner Password Credentials Grant of
+OAuth2. In this grant, a trusted client exchanges the end user's credentials
+for an access token and (possibly) a refresh token. The request needs to be made
+by an authenticated user but happens _on behalf_ of another authenticated user
+(the one whose credentials are passed as request parameters). This grant type is
+not suitable or designed for the self-service user creation of tokens.
+
+`refresh_token`:::
+This grant type implements the Refresh Token Grant of OAuth2.
+In this grant a user exchanges a previously issued refresh token for a new access token and a new refresh token.
 
 `password`::
-(string) The user's password. If you specify the `password` grant type, this 
+(Optional^*^, string) The user's password. If you specify the `password` grant type, this
 parameter is required. This parameter is not valid with any other supported
 grant type.
 
 `kerberos_ticket`::
-(string) base64 encoded kerberos ticket. If you specify the `_kerberos` grant type,
-this parameter is required. This parameter is not valid with any other supported
-grant type.
+(Optional^*^, string) The base64 encoded kerberos ticket. If you specify the
+`_kerberos` grant type, this parameter is required. This parameter is not valid
+with any other supported grant type.
 
 `refresh_token`::
-(string) If you specify the `refresh_token` grant type, this parameter is 
-required. It contains the string that was returned when you created the token 
-and enables you to extend its life. This parameter is not valid with any other
+(Optional^*^, string) The string that was returned when you created the token, 
+which enables you to extend its life. If you specify the `refresh_token` grant
+type, this parameter is required. This parameter is not valid with any other
 supported grant type.
 
 `scope`::
-(string) The scope of the token. Currently tokens are only issued for a scope of
+(Optional, 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`::
-(string) The username that identifies the user. If you specify the `password` 
+(Optional^*^, string) The username that identifies the user. If you specify the `password` 
 grant type, this parameter is required. This parameter is not valid with any
 other supported grant type.