Invalidate a token Generally available; Added in 5.5.0

DELETE /_security/oauth2/token
Api key auth Basic auth Bearer auth

The access tokens returned by the get token API have a finite period of time for which they are valid. After that time period, they can no longer be used. The time period is defined by the xpack.security.authc.token.timeout setting.

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.

NOTE: 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.

application/json

Body Required

  • token string

    An access token. This parameter cannot be used if any of refresh_token, realm_name, or username are used.

  • refresh_token string

    A refresh token. This parameter cannot be used if any of refresh_token, realm_name, or username are used.

  • realm_name string

    The name of an authentication realm. This parameter cannot be used with either refresh_token or token.

  • username string

    The username of a user. This parameter cannot be used with either refresh_token or token.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • error_count number Required

      The number of errors that were encountered when invalidating the tokens.

    • error_details array[object]

      Details about the errors. This field is not present in the response when error_count is 0.

      Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      Hide error_details attributes Show error_details attributes object
      • type string Required

        The type of error

      • reason string | null

        A human-readable explanation of the error, in English.

        One of:
        string-1 string string-2 string | null
      • stack_trace string

        The server stack trace. Present only if the error_trace=true parameter was sent with the request.

      • caused_by object

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      • root_cause array[object]

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      • suppressed array[object]

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

    • invalidated_tokens number Required

      The number of the tokens that were invalidated as part of this request.

    • previously_invalidated_tokens number Required

      The number of tokens that were already invalidated.
DELETE /_security/oauth2/token 
DELETE /_security/oauth2/token
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}
resp = client.security.invalidate_token(
    token="dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
)
const response = await client.security.invalidateToken({
  token:
    "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
});
response = client.security.invalidate_token(
  body: {
    "token": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
  }
)
$resp = $client->security()->invalidateToken([
    "body" => [
        "token" => "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
    ],
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"token":"dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="}' "$ELASTICSEARCH_URL/_security/oauth2/token"
client.security().invalidateToken(i -> i
    .token("dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==")
);
Request examples
Run `DELETE /_security/oauth2/token` to invalidate an access token. 
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}
Run `DELETE /_security/oauth2/token` to invalidate a refresh token. 
{
  "refresh_token" : "vLBPvmAB6KvwvJZr27cS"
}
Run `DELETE /_security/oauth2/token` to invalidate all access tokens and refresh tokens for the `saml1` realm. 
{
  "realm_name" : "saml1"
}
Run `DELETE /_security/oauth2/token` to invalidate all access tokens and refresh tokens for the user `myuser` in all realms. 
{
  "username" : "myuser"
}
Run `DELETE /_security/oauth2/token` to invalidate all access tokens and refresh tokens for the user `myuser` in the `saml1` realm. 
{
  "username" : "myuser",
  "realm_name" : "saml1"
}
Response examples (200)
A partially successful response from `DELETE /_security/oauth2/token`. The response includes the number of the tokens that were invalidated, the number of errors that were encountered when invalidating the tokens, and details about these errors. 
{
  "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]"
      }
    }
  ]
}