NOTE: You are looking at documentation for an older release. For the latest information, see the current release documentation.

« Invalidate API key API SSL certificate API »

› › ›

Invalidate token API

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Invalidate token API

edit

Invalidates one or more access tokens or refresh tokens.

Request

edit

DELETE /_xpack/security/oauth2/token

Description

edit

The access 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.

The refresh tokens returned by the get token API are only valid for 24 hours. They can also be used exactly once.

If you want to invalidate one or more access or refresh tokens immediately, use this invalidate token API.

Request Body

edit

The following parameters can be specified in the body of a DELETE request and pertain to invalidating tokens:

token (optional): (string) An access token. This parameter cannot be used any of refresh_token, realm_name or username are used.
refresh_token (optional): (string) A refresh token. This parameter cannot be used any of refresh_token, realm_name or username are used.
realm_name (optional): (string) The name of an authentication realm. This parameter cannot be used with either refresh_token or token.
username (optional): (string) The username of a user. This parameter cannot be used with either refresh_token or token

While all parameters are optional, at least one of them is required. More specifically, either one of token or refresh_token parameters is required. If none of these two are specified, then realm_name and/or username need to be specified.

Examples

edit

The following example invalidates the specified token immediately:

DELETE /_xpack/security/oauth2/token
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}

whereas the following example invalidates the specified refresh token immediately:

DELETE /_xpack/security/oauth2/token
{
  "refresh_token" : "movUJjPGRRC0PQ7+NW0eag"
}

The following example invalidates all access tokens and refresh tokens for the saml1 realm immediately:

DELETE /_xpack/security/oauth2/token
{
  "realm_name" : "saml1"
}

The following example invalidates all access tokens and refresh tokens for the user myuser in all realms immediately:

DELETE /_xpack/security/oauth2/token
{
  "username" : "myuser"
}

Finally, the following example invalidates all access tokens and refresh tokens for the user myuser in the saml1 realm immediately:

DELETE /_xpack/security/oauth2/token
{
  "username" : "myuser",
  "realm_name" : "saml1"
}

A successful call returns a JSON structure that contains the number of tokens that were invalidated, the number of tokens that had already been invalidated, and potentially a list of errors encountered while invalidating specific tokens.

{
  "invalidated_tokens":9, 
  "previously_invalidated_tokens":15, 
  "error_count":2, 
  "error_details":[ 
    {
      "type":"exception",
      "reason":"Elasticsearch exception [type=exception, reason=foo]",
      "caused_by":{
        "type":"exception",
        "reason":"Elasticsearch exception [type=illegal_argument_exception, reason=bar]"
      }
    },
    {
      "type":"exception",
      "reason":"Elasticsearch exception [type=exception, reason=boo]",
      "caused_by":{
        "type":"exception",
        "reason":"Elasticsearch exception [type=illegal_argument_exception, reason=far]"
      }
    }
  ]
}

	The number of the tokens that were invalidated as part of this request.
	The number of tokens that were already invalidated.
	The number of errors that were encountered when invalidating the tokens.
	Details about these errors. This field is not present in the response when `error_count` is 0.

« Invalidate API key API SSL certificate API »