本地英文版地址: ../en/security-api-invalidate-api-key.html
Invalidate API key APIedit
Invalidates one or more API keys.
Requestedit
DELETE /_security/api_key
Prerequisitesedit
-
To use this API, you must have at least the
manage_api_keycluster privilege.
Descriptionedit
The API keys created by create API Key can be invalidated using this API.
Request bodyedit
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_nameorusernameare used. -
name -
(Optional, string) An API key name. This parameter cannot be used with any of
id,realm_nameorusernameare used. -
realm_name -
(Optional, string) The name of an authentication realm. This parameter cannot be
used with either
idornameor whenownerflag is set totrue. -
username -
(Optional, string) The username of a user. This parameter cannot be used with
either
idornameor whenownerflag is set totrue. -
owner - (Optional, boolean) A boolean flag that can be used to query API keys owned by the currently authenticated user. Defaults to false. 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.
At least one of "id", "name", "username" and "realm_name" must be specified if "owner" is "false" (default).
Response bodyedit
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.
Examplesedit
If you create an API key as follows:
POST /_security/api_key
{
"name": "my-api-key"
}
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"
}
The following example invalidates the API key identified by the specified id if
it is owned by the currently authenticated user immediately:
DELETE /_security/api_key
{
"id" : "VuaCfGcBCdbkQm-e5aOx",
"owner" : "true"
}
The following example invalidates all API keys owned by the currently authenticated user immediately:
DELETE /_security/api_key
{
"owner" : "true"
}
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"
}
{
"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"
}
}
]
}