178 lines
4.5 KiB
Plaintext
178 lines
4.5 KiB
Plaintext
[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 `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`.
|
|
|
|
NOTE: While all parameters are optional, at least one of them is required.
|
|
|
|
==== Examples
|
|
|
|
If you create an API key as follows:
|
|
|
|
[source, js]
|
|
------------------------------------------------------------
|
|
POST /_security/api_key
|
|
{
|
|
"name": "my-api-key",
|
|
"role_descriptors": {}
|
|
}
|
|
------------------------------------------------------------
|
|
// 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.
|