---
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/4493/api/doc/elasticsearch/v9/operation/operation-security-invalidate-token
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v9/operation/operation-security-invalidate-token
products:
  - Elasticsearch
---

# Invalidate a token

Availability: Generally available since 5.5

## Paths

- `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.
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.

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs support key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  To get API keys, use the `/_security/api_key` APIs.
- Basic: `Authorization: Basic <credentials>`
- Bearer: `Authorization: Bearer <token>`
  Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API.
  For examples, refer to [Token-based authentication services](https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/token-based-authentication-services)

## 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) — 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` (object[])
  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` (object) — recursive
    Same fields as `error_details`
  - `root_cause` (object[]) — recursive
    Same fields as `error_details`
  - `suppressed` (object[]) — 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]"
      }
    }
  ]
}
```