IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Has privileges API Invalidate token API »

› › ›

Invalidate API key API

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

Invalidate API key API

edit

Invalidates one or more API keys.

Request

edit

DELETE /_security/api_key

Description

edit

The API keys created by create API Key can be invalidated using this API.

Request Body

edit

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 api_key_id or api_key_name.
username (optional): (string) The username of a user. This parameter cannot be used with either api_key_id or api_key_name.

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

Examples

edit

If you create an API key as follows:

POST /_security/api_key
{
  "name": "my-api-key",
  "role_descriptors": {}
}

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

{
  "id":"VuaCfGcBCdbkQm-e5aOx",
  "name":"my-api-key",
  "api_key":"ui2lp2axTNmsyakw9tvNnw"
}

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

DELETE /_security/api_key
{
  "id" : "VuaCfGcBCdbkQm-e5aOx"
}

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

DELETE /_security/api_key
{
  "name" : "my-api-key"
}

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

DELETE /_security/api_key
{
  "realm_name" : "native1"
}

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

DELETE /_security/api_key
{
  "username" : "myuser"
}

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

DELETE /_security/api_key
{
  "username" : "myuser",
  "realm_name" : "native1"
}

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.

{
  "invalidated_api_keys": [ 
    "api-key-id-1"
  ],
  "previously_invalidated_api_keys": [ 
    "api-key-id-2",
    "api-key-id-3"
  ],
  "error_count": 2, 
  "error_details": [ 
    {
      "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"
      }
    }
  ]
}

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

« Has privileges API Invalidate token API »