[DOCS] Adjust Invalidate Token REST API docs (#35622)

- Renames API to Invalidate Token
- Explicitly calls out the possibility to invalidate refresh tokens
via this API

Author: jkakavas

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

@@ -77,7 +77,6 @@ include::security/create-users.asciidoc[]
 include::security/delete-app-privileges.asciidoc[]
 include::security/delete-role-mappings.asciidoc[]
 include::security/delete-roles.asciidoc[]
-include::security/delete-tokens.asciidoc[]
 include::security/delete-users.asciidoc[]
 include::security/disable-users.asciidoc[]
 include::security/enable-users.asciidoc[]
@@ -87,4 +86,5 @@ include::security/get-roles.asciidoc[]
 include::security/get-tokens.asciidoc[]
 include::security/get-users.asciidoc[]
 include::security/has-privileges.asciidoc[]
+include::security/invalidate-tokens.asciidoc[]
 include::security/ssl.asciidoc[]

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

@@ -29,7 +29,7 @@ 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 
-<<security-api-invalidate-token,delete token API>>.
+<<security-api-invalidate-token,invalidate token API>>.
 
 
 ==== Request Body

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

@@ -1,31 +1,39 @@
 [role="xpack"]
 [[security-api-invalidate-token]]
-=== Delete token API
+=== Invalidate token API
 
-Invalidates a bearer token for access without requiring basic authentication.
+Invalidates an access token or a refresh token.
 
 ==== Request
 
 `DELETE /_xpack/security/oauth2/token`
 
 ==== Description
 
-The tokens returned by the <<security-api-get-token,get token API>> have a 
+The access 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.
+The refresh tokens returned by the <<security-api-get-token,get token API>> are
+only valid for 24 hours. They can also be used exactly once.
+
+If you want to invalidate an access or refresh token immediately, use this invalidate token API.
 
 
 ==== Request Body
 
 The following parameters can be specified in the body of a DELETE request and
-pertain to deleting a token:
+pertain to invalidating a token:
+
+`token` (optional)::
+(string) An access token. This parameter cannot be used when `refresh_token` is used.
+
+`refresh_token` (optional)::
+(string) A refresh token. This parameter cannot be used when `token` is used.
 
-`token` (required)::
-(string) An access token.
+NOTE: One of `token` or `refresh_token` parameters is required.
 
 ==== Examples
 
@@ -40,6 +48,17 @@ DELETE /_xpack/security/oauth2/token
 --------------------------------------------------
 // NOTCONSOLE
 
+whereas the following example invalidates the specified refresh token immediately:
+
+[source,js]
+--------------------------------------------------
+DELETE /_xpack/security/oauth2/token
+{
+  "refresh_token" : "movUJjPGRRC0PQ7+NW0eag"
+}
+--------------------------------------------------
+// NOTCONSOLE
+
 A successful call returns a JSON structure that indicates whether the token
 has already been invalidated.