OpenSearch/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc

[role="xpack"]
[[security-api-invalidate-api-key]]
=== Invalidate API key API
++++
<titleabbrev>Invalidate API key</titleabbrev>
++++

Invalidates one or more API keys.

==== Request

`DELETE /_security/api_key`

==== Description

The API keys created by <<security-api-create-api-key,create API Key>> can be
invalidated using this API.

==== Request Body

The following parameters can be specified in the body of a DELETE request and
pertain to invalidating api keys:

`id` (optional)::
(string) An API key id. This parameter cannot be used with any of `name`,
`realm_name` or `username` are used.

`name` (optional)::
(string) An API key name. This parameter cannot be used with any of `id`,
`realm_name` or `username` are used.

`realm_name` (optional)::
(string) The name of an authentication realm. This parameter cannot be used with
either `id` or `name`.

`username` (optional)::
(string) The username of a user. This parameter cannot be used with either
`id` or `name`.

NOTE: While all parameters are optional, at least one of them is required.

==== Authorization

To use this API, you must have at least the `manage_api_key` cluster privilege.

==== Examples

If you create an API key as follows:

[source, js]
------------------------------------------------------------
POST /_security/api_key
{
  "name": "my-api-key"
}
------------------------------------------------------------
// CONSOLE
// TEST

A successful call returns a JSON structure that provides
API key information. For example:

[source,js]
--------------------------------------------------
{
  "id":"VuaCfGcBCdbkQm-e5aOx",
  "name":"my-api-key",
  "api_key":"ui2lp2axTNmsyakw9tvNnw"
}
--------------------------------------------------
// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]

The following example invalidates the API key identified by specified `id` immediately:

[source,js]
--------------------------------------------------
DELETE /_security/api_key
{
  "id" : "VuaCfGcBCdbkQm-e5aOx"
}
--------------------------------------------------
// CONSOLE
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
// TEST[continued]

The following example invalidates the API key identified by specified `name` immediately:

[source,js]
--------------------------------------------------
DELETE /_security/api_key
{
  "name" : "my-api-key"
}
--------------------------------------------------
// CONSOLE
// TEST

The following example invalidates all API keys for the `native1` realm
immediately:

[source,js]
--------------------------------------------------
DELETE /_security/api_key
{
  "realm_name" : "native1"
}
--------------------------------------------------
// CONSOLE
// TEST

The following example invalidates all API keys for the user `myuser` in all
realms immediately:

[source,js]
--------------------------------------------------
DELETE /_security/api_key
{
  "username" : "myuser"
}
--------------------------------------------------
// CONSOLE
// TEST

Finally, the following example invalidates all API keys for the user `myuser` in
 the `native1` realm immediately:

[source,js]
--------------------------------------------------
DELETE /_security/api_key
{
  "username" : "myuser",
  "realm_name" : "native1"
}
--------------------------------------------------
// CONSOLE
// TEST

A successful call returns a JSON structure that contains the ids of the API keys that were invalidated, the ids
of the API keys that had already been invalidated, and potentially a list of errors encountered while invalidating
specific api keys.

[source,js]
--------------------------------------------------
{
  "invalidated_api_keys": [ <1>
    "api-key-id-1"
  ],
  "previously_invalidated_api_keys": [ <2>
    "api-key-id-2",
    "api-key-id-3"
  ],
  "error_count": 2, <3>
  "error_details": [ <4>
    {
      "type": "exception",
      "reason": "error occurred while invalidating api keys",
      "caused_by": {
        "type": "illegal_argument_exception",
        "reason": "invalid api key id"
      }
    },
    {
      "type": "exception",
      "reason": "error occurred while invalidating api keys",
      "caused_by": {
        "type": "illegal_argument_exception",
        "reason": "invalid api key id"
      }
    }
  ]
}
--------------------------------------------------
// NOTCONSOLE

<1> The ids of the API keys that were invalidated as part of this request.
<2> The ids of the API keys that were already invalidated.
<3> The number of errors that were encountered when invalidating the API keys.
<4> Details about these errors. This field is not present in the response when
    `error_count` is 0.