[DOCS] Splits the token APIs into separate pages (#32865)

Author: lcawl

docs/reference/redirects.asciidoc

@@ -506,4 +506,12 @@ You can use the following APIs to add, remove, and retrieve roles in the native
 
 * <<security-api-put-role,Create role>>, <<security-api-delete-role,Delete role>>
 * <<security-api-clear-role-cache,Clear roles cache>>
-* <<security-api-get-role,Get roles>>
+* <<security-api-get-role,Get roles>>
+
+[role="exclude",id="security-api-tokens"]
+=== Token management APIs
+
+You can use the following APIs to create and invalidate bearer tokens for access
+without requiring basic authentication:
+
+* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>

x-pack/docs/en/rest-api/security.asciidoc

@@ -9,7 +9,6 @@ You can use the following APIs to perform {security} activities.
 * <<security-api-privileges>>
 * <<security-api-role-mapping>>
 * <<security-api-ssl>>
-* <<security-api-tokens>>
 * <<security-api-users>>
 
 [float]
@@ -22,15 +21,25 @@ You can use the following APIs to add, remove, and retrieve roles in the native
 * <<security-api-clear-role-cache,Clear roles cache>>
 * <<security-api-get-role,Get roles>>
 
+[float]
+[[security-token-apis]]
+=== Tokens
+
+You can use the following APIs to create and invalidate bearer tokens for access
+without requiring basic authentication:
+
+* <<security-api-get-token,Get token>>, <<security-api-invalidate-token,Invalidate token>>
+
 include::security/authenticate.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/clear-cache.asciidoc[]
 include::security/clear-roles-cache.asciidoc[]
 include::security/create-roles.asciidoc[]
 include::security/delete-roles.asciidoc[]
+include::security/delete-tokens.asciidoc[]
 include::security/get-roles.asciidoc[]
+include::security/get-tokens.asciidoc[]
 include::security/privileges.asciidoc[]
 include::security/role-mapping.asciidoc[]
 include::security/ssl.asciidoc[]
-include::security/tokens.asciidoc[]
 include::security/users.asciidoc[]

x-pack/docs/en/rest-api/security/delete-tokens.asciidoc

@@ -0,0 +1,54 @@
+[role="xpack"]
+[[security-api-invalidate-token]]
+=== Delete token API
+
+Invalidates a bearer token for access without requiring basic authentication.
+
+==== Request
+
+`DELETE /_xpack/security/oauth2/token`
+
+==== Description
+
+The tokens returned by the <<security-api-get-token,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. That time period is defined by the 
+`xpack.security.authc.token.timeout` setting. For more information, see 
+<<token-service-settings>>.
+
+If you want to invalidate a token immediately, use this delete token API.
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a DELETE request and
+pertain to deleting a token:
+
+`token` (required)::
+(string) An access token.
+
+==== Examples
+
+The following example invalidates the specified token immediately:
+
+[source,js]
+--------------------------------------------------
+DELETE /_xpack/security/oauth2/token
+{
+  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+A successful call returns a JSON structure that indicates whether the token
+has already been invalidated.
+
+[source,js]
+--------------------------------------------------
+{
+  "created" : true <1>
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+<1> When a token has already been invalidated, `created` is set to false.

x-pack/docs/en/rest-api/security/tokens.asciidoc renamed to x-pack/docs/en/rest-api/security/get-tokens.asciidoc

@@ -1,15 +1,12 @@
 [role="xpack"]
-[[security-api-tokens]]
-=== Token Management APIs
+[[security-api-get-token]]
+=== Get token API
 
-The `token` API enables you to create and invalidate bearer tokens for access
-without requiring basic authentication.
+Creates a bearer token for access without requiring basic authentication.
 
 ==== Request
 
-`POST /_xpack/security/oauth2/token` +
-
-`DELETE /_xpack/security/oauth2/token`
+`POST /_xpack/security/oauth2/token` 
 
 ==== Description
 
@@ -19,20 +16,20 @@ you can explicitly enable the `xpack.security.authc.token.enabled` setting. When
 you are running in production mode, a bootstrap check prevents you from enabling 
 the token service unless you also enable TLS on the HTTP interface. 
 
-The Get Token API takes the same parameters as a typical OAuth 2.0 token API
+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
+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
+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. That time
 period is defined by the `xpack.security.authc.token.timeout` setting. For more
 information, see <<token-service-settings>>.
 
-If you want to invalidate a token immediately, you can do so by using the Delete
-Token API.
+If you want to invalidate a token immediately, you can do so by using the 
+<<security-api-invalidate-token,delete token API>>.
 
 
 ==== Request Body
@@ -41,28 +38,28 @@ 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.
+(string) The type of grant. Valid grant types are: `password` and `refresh_token`.
 
-`password` (required)::
-(string) The user's password.
+`password`::
+(string) The user's password. If you specify the `password` grant type, this 
+parameter is required. 
+
+`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.
 
 `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.
+`username`::
+(string) The username that identifies the user. If you specify the `password` 
+grant type, this parameter is required. 
 
 ==== Examples
-[[security-api-get-token]]
-To obtain a token, submit a POST request to the `/_xpack/security/oauth2/token`
-endpoint.
+
+The following example obtains a token for the `test_admin` user:
 
 [source,js]
 --------------------------------------------------
@@ -101,8 +98,8 @@ curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvb
 // NOTCONSOLE
 
 [[security-api-refresh-token]]
-To extend the life of an existing token, the token api may be called again with the refresh
-token within 24 hours of the token's creation.
+To extend the life of an existing token, you can call the API again with the 
+refresh token within 24 hours of the token's creation. For example:
 
 [source,js]
 --------------------------------------------------
@@ -116,7 +113,8 @@ POST /_xpack/security/oauth2/token
 // TEST[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
 // TEST[continued]
 
-The API will return a new token and refresh token. Each refresh token may only be used one time.
+The API will return a new token and refresh token. Each refresh token may only 
+be used one time.
 
 [source,js]
 --------------------------------------------------
@@ -128,32 +126,4 @@ The API will return a new token and refresh token. Each refresh token may only b
 }
 --------------------------------------------------
 // TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
-// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
-
-[[security-api-invalidate-token]]
-If a token must be invalidated immediately, you can do so by submitting a DELETE
-request to `/_xpack/security/oauth2/token`.  For example:
-
-[source,js]
---------------------------------------------------
-DELETE /_xpack/security/oauth2/token
-{
-  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
-}
---------------------------------------------------
-// CONSOLE
-// TEST[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
-// TEST[continued]
-
-A successful call returns a JSON structure that indicates whether the token
-has already been invalidated.
-
-[source,js]
---------------------------------------------------
-{
-  "created" : true <1>
-}
---------------------------------------------------
-// TESTRESPONSE
-
-<1> When a token has already been invalidated, `created` is set to false.
+// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.get_token.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.get_token": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html#security-api-get-token",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-get-token.html",
     "methods": [ "POST" ],
     "url": {
       "path": "/_xpack/security/oauth2/token",

x-pack/plugin/src/test/resources/rest-api-spec/api/xpack.security.invalidate_token.json

@@ -1,6 +1,6 @@
 {
   "xpack.security.invalidate_token": {
-    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-tokens.html#security-api-invalidate-token",
+    "documentation": "https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-invalidate-token.html",
     "methods": [ "DELETE" ],
     "url": {
       "path": "/_xpack/security/oauth2/token",