Invalidate token API

Invalidate token API

New API reference

For the most up-to-date API details, refer to Security APIs.

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:

resp = client.security.get_token(
    grant_type="client_credentials",
)
print(resp)

const response = await client.security.getToken({
  grant_type: "client_credentials",
});
console.log(response);

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:

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

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

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:

resp = client.security.get_token(
    grant_type="password",
    username="test_admin",
    password="x-pack-test-password",
)
print(resp)

const response = await client.security.getToken({
  grant_type: "password",
  username: "test_admin",
  password: "x-pack-test-password",
});
console.log(response);

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:

resp = client.security.invalidate_token(
    refresh_token="vLBPvmAB6KvwvJZr27cS",
)
print(resp)

const response = await client.security.invalidateToken({
  refresh_token: "vLBPvmAB6KvwvJZr27cS",
});
console.log(response);

DELETE /_security/oauth2/token
{
  "refresh_token" : "vLBPvmAB6KvwvJZr27cS"
}

The following example invalidates all access tokens and refresh tokens for the saml1 realm immediately:

resp = client.security.invalidate_token(
    realm_name="saml1",
)
print(resp)

const response = await client.security.invalidateToken({
  realm_name: "saml1",
});
console.log(response);

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:

resp = client.security.invalidate_token(
    username="myuser",
)
print(resp)

const response = await client.security.invalidateToken({
  username: "myuser",
});
console.log(response);

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:

resp = client.security.invalidate_token(
    username="myuser",
    realm_name="saml1",
)
print(resp)

const response = await client.security.invalidateToken({
  username: "myuser",
  realm_name: "saml1",
});
console.log(response);

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]"
      }
    }
  ]
}