Docs
Elasticsearch Guide [8.1] » REST APIs » Security APIs » Invalidate token API
« Invalidate API key API OpenID Connect prepare authentication API »

Invalidate token API

Invalidates one or more access tokens or refresh tokens.

Request

DELETE /_security/oauth2/token

Description

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

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.

Response body

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.

Examples

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,
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
      ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
      },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
      },
    "authentication_type" : "realm"
  }
}

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",
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
      ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
      },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
      },
    "authentication_type" : "realm"
  }
}

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"
}
{
  "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 OpenID Connect prepare authentication API »