---
type: api
title: Invalidate a token
description: The access tokens returned by the get token API have a finite period of time for which they are valid.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-invalidate-token
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/operation/operation-security-invalidate-token
products:
  - Elasticsearch
---

# Invalidate a token

Availability: 5.5+

## Paths

- `DELETE` `/_security/oauth2/token`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/authentication#bearerauth)

## Description

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.

## Request Body

`application/json`

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

## Response

`application/json`

- `error_count` (number)
  The number of errors that were encountered when invalidating the tokens.
- `error_details` ([] ErrorCause)
  Details about the errors.
This field is not present in the response when `error_count` is `0`.
  - `type` (string)
    The type of error
  - `reason` (union string) — nullable
    A human-readable explanation of the error, in English.
    One of: `string`
  - `stack_trace` (string)
    The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
  - `caused_by` ({} ErrorCause) — recursive
    Same fields as `error_details`
  - `root_cause` ([] ErrorCause) — recursive
    Same fields as `error_details`
  - `suppressed` ([] ErrorCause) — recursive
    Same fields as `error_details`
- `invalidated_tokens` (number)
  The number of the tokens that were invalidated as part of this request.
- `previously_invalidated_tokens` (number)
  The number of tokens that were already invalidated.
## Code Examples

#### Console

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

#### JavaScript

```javascript
const response = await client.security.invalidateToken({
  token:
    "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
});
```

#### Python

```python
resp = client.security.invalidate_token(
    token="dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
)
```

#### curl

```curl
curl -X DELETE "$ELASTICSEARCH_URL/_security/oauth2/token" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
  }'
```

#### Java

```java
client.security().invalidateToken(i -> i
    .token("dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==")
);
```

#### C#

```c#
var response = await client.Security
    .InvalidateTokenAsync(d1 => d1
        .Token("dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==")
    );
```

#### PHP

```php
$resp = $client->security()->invalidateToken([
    "body" => [
        "token" => "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
    ],
]);
```

#### Ruby

```ruby
response = client.security.invalidate_token(
  body: {
    "token": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
  }
)
```

## Response Examples

#### Security invalidate token response example1

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.

```json
{
  "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]"
      }
    }
  ]
}
```