DELETE /_security/oauth2/token

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.

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

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.

For example, if you create a token using the client_credentials grant type as follows:

POST /_security/oauth2/token
{
  "grant_type" : "client_credentials"
}

The get token API returns the following information about the access token:

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200
}

This access token can now be immediately invalidated, as shown in the following example:

DELETE /_security/oauth2/token
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}

If you used the password grant type to obtain a token for a user, the response might also contain a refresh token. For example:

POST /_security/oauth2/token
{
  "grant_type" : "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password"
}

The get token API returns the following information:

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

The refresh token can now also be immediately invalidated as shown in the following example:

DELETE /_security/oauth2/token
{
  "refresh_token" : "vLBPvmAB6KvwvJZr27cS"
}

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

DELETE /_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 /_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 /_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]"
      }
    }
  ]
}