Invalidate API keys Generally available

DELETE /_security/api_key
Api key auth

This API invalidates API keys created by the create API key or grant API key APIs. Invalidated API keys fail authentication, but they can still be viewed using the get API key information and query API key information APIs, for at least the configured retention period, until they are automatically deleted.

To use this API, you must have at least the manage_security, manage_api_key, or manage_own_api_key cluster privileges. The manage_security privilege allows deleting any API key, including both REST and cross cluster API keys. The manage_api_key privilege allows deleting any REST API key, but not cross cluster API keys. The manage_own_api_key only allows deleting REST API keys that are owned by the user. In addition, with the manage_own_api_key privilege, an invalidation request must be issued in one of the three formats:

  • Set the parameter owner=true.
  • Or, set both username and realm_name to match the user's identity.
  • Or, if the request is issued by an API key, that is to say an API key invalidates itself, specify its ID in the ids field.

Required authorization

  • Cluster privileges: manage_api_key,manage_own_api_key
application/json

Body Required

  • id string
  • ids array[string]

    A list of API key ids. This parameter cannot be used with any of name, realm_name, or username.

  • name string

    An API key name. This parameter cannot be used with any of ids, realm_name or username.

  • owner boolean

    Query API keys owned by the currently authenticated user. The realm_name or username parameters cannot be specified when this parameter is set to true as they are assumed to be the currently authenticated ones.

    NOTE: At least one of ids, name, username, and realm_name must be specified if owner is false.

    Default value is false.

  • realm_name string

    The name of an authentication realm. This parameter cannot be used with either ids or name, or when owner flag is set to true.

  • username string

    The username of a user. This parameter cannot be used with either ids or name or when owner flag is set to true.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • error_count number Required

      The number of errors that were encountered when invalidating the API keys.

    • error_details array[object]

      Details about the errors. This field is not present in the response when error_count is 0.

      Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      Hide error_details attributes Show error_details attributes object
      • type string Required

        The type of error

      • reason string | null

        A human-readable explanation of the error, in English.

        One of:
        string-1 string string-2 string | null
      • stack_trace string

        The server stack trace. Present only if the error_trace=true parameter was sent with the request.

      • caused_by object

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      • root_cause array[object]

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

      • suppressed array[object]

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

        Cause and details about a request failure. This class defines the properties common to all error types. Additional details are also provided, that depend on the error type.

    • invalidated_api_keys array[string] Required

      The IDs of the API keys that were invalidated as part of this request.

    • previously_invalidated_api_keys array[string] Required

      The IDs of the API keys that were already invalidated.
DELETE /_security/api_key 
DELETE /_security/api_key
{
  "ids" : [ "VuaCfGcBCdbkQm-e5aOx" ]
}
resp = client.security.invalidate_api_key(
    ids=[
        "VuaCfGcBCdbkQm-e5aOx"
    ],
)
const response = await client.security.invalidateApiKey({
  ids: ["VuaCfGcBCdbkQm-e5aOx"],
});
response = client.security.invalidate_api_key(
  body: {
    "ids": [
      "VuaCfGcBCdbkQm-e5aOx"
    ]
  }
)
$resp = $client->security()->invalidateApiKey([
    "body" => [
        "ids" => array(
            "VuaCfGcBCdbkQm-e5aOx",
        ),
    ],
]);
curl -X DELETE -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"ids":["VuaCfGcBCdbkQm-e5aOx"]}' "$ELASTICSEARCH_URL/_security/api_key"
client.security().invalidateApiKey(i -> i
    .ids("VuaCfGcBCdbkQm-e5aOx")
);
Request examples
Run `DELETE /_security/api_key` to invalidate the API keys identified by ID. 
{
  "ids" : [ "VuaCfGcBCdbkQm-e5aOx" ]
}
Run `DELETE /_security/api_key` to invalidate the API keys identified by name. 
{
  "name" : "my-api-key"
}
Run `DELETE /_security/api_key` to invalidate all API keys for the `native1` realm. 
{
  "realm_name" : "native1"
}
Run `DELETE /_security/api_key` to invalidate all API keys for the user `myuser` in all realms. 
{
  "username" : "myuser"
}
Run `DELETE /_security/api_key` to invalidate the API keys identified by ID if they are owned by the currently authenticated user. 
{
  "ids" : ["VuaCfGcBCdbkQm-e5aOx"],
  "owner" : "true"
}
Run `DELETE /_security/api_key` to invalidate all API keys for the user `myuser` in the `native1` realm . 
{
  "username" : "myuser",
  "realm_name" : "native1"
}
Response examples (200)
A successful response from `DELETE /_security/api_key`. 
{
  "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"
      }
    }
  ]
}