Elasticsearch Handling Expired Tokens in Elasticsearch

By Opster Team

Updated: Nov 2, 2023

| 2 min read


In Elasticsearch, security features such as authentication and authorization are essential for protecting sensitive data and controlling access to cluster resources. One common method for managing user access is through the use of tokens, which are temporary credentials that grant users specific permissions for a limited time. However, when a token expires, it can lead to issues such as denied access or interrupted operations. In this article, we will discuss how to handle expired tokens in Elasticsearch, including detecting token expiration, refreshing tokens, and managing token lifetimes. If you want to learn about token expired – how to solve this Elasticsearch error, check out this guide.

Detecting Token Expiration

When using tokens for authentication, it is crucial to be aware of their expiration status. An expired token will result in a 401 Unauthorized response from the Elasticsearch cluster. To detect token expiration, you can monitor the response headers of your API requests. The “WWW-Authenticate” header will contain information about the token’s status, including its expiration time. For example:

WWW-Authenticate: Bearer realm="security", error="invalid_token", error_description="The access token expired"

If you encounter this error, it is necessary to refresh the token or obtain a new one to regain access to the cluster.

Refreshing Tokens

To refresh an expired token, you can use the token API in Elasticsearch. When you initially obtain an access token, you will also receive a refresh token. You can use this refresh token to request a new access token without requiring the user to re-authenticate. Here’s an example of how to refresh a token using the token API:

POST /_security/oauth2/token
  "grant_type": "refresh_token",
  "refresh_token": "<your_refresh_token>"

The response will contain a new access token and refresh token, which you can use for subsequent requests:

  "access_token": "<new_access_token>",
  "type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<new_refresh_token>"

It is essential to replace the expired token with the new access token in your application to continue accessing the cluster resources.

Managing Token Lifetimes

To minimize the impact of expired tokens, you can configure token lifetimes according to your security requirements and use case. In Elasticsearch, you can set the token lifetime using the “xpack.security.authc.token.timeout” setting in the “elasticsearch.yml” configuration file. The default value is 20 minutes, but you can adjust it to a longer or shorter duration as needed. For example:

xpack.security.authc.token.timeout: "1h"

This setting will configure the access token to expire after one hour. Note that increasing the token lifetime may increase the risk of unauthorized access if a token is compromised, so it is essential to balance security and usability when configuring token lifetimes.

In addition to the access token lifetime, you can also configure the refresh token lifetime using the “xpack.security.authc.token.refresh_token.expires_in” setting in the “elasticsearch.yml” file. By default, refresh tokens are valid for 24 hours. You can adjust this value to control how long users can refresh their access tokens without re-authenticating:

xpack.security.authc.token.refresh_token.expires_in: "48h"

This setting will configure the refresh token to expire after 48 hours.


Handling expired tokens is a critical aspect of managing user access and maintaining security in Elasticsearch clusters. By detecting token expiration, refreshing tokens when necessary, and configuring token lifetimes according to your requirements, you can ensure a smooth and secure user experience while accessing cluster resources. Always remember to balance security and usability when configuring token settings to minimize the risk of unauthorized access and maintain the overall integrity of your Elasticsearch environment.

How helpful was this guide?

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?