Skip to content

Commit

Permalink
Docs for Get API key active_only flag (#98313)
Browse files Browse the repository at this point in the history
Docs for #98259.
  • Loading branch information
n1v0lg authored Aug 10, 2023
1 parent 225503a commit ddc470c
Showing 1 changed file with 16 additions and 3 deletions.
19 changes: 16 additions & 3 deletions x-pack/docs/en/rest-api/security/get-api-keys.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ Retrieves information for one or more API keys.
[[security-api-get-api-key-prereqs]]
==== {api-prereq-title}

* To use this API, you must have at least the `manage_own_api_key` or the
* To use this API, you must have at least the `manage_own_api_key` or the
`read_security` cluster privileges.
** If you only have the `manage_own_api_key` privilege, this API only returns
the API keys that you own.
the API keys that you own.
+
NOTE: Authenticating with an API key that has the `manage_own_api_key` privilege
does not allow retrieving the authenticated user's own keys. Instead,
does not allow retrieving the authenticated user's own keys. Instead,
authenticate the user with basic credentials.
** If you have `read_security`, `manage_api_key` or greater
privileges (including `manage_security`), this API returns all API keys
Expand Down Expand Up @@ -67,6 +67,12 @@ associated with the API key. An API key's actual permission is the intersection
its <<api-key-role-descriptors,assigned role descriptors>> and the owner user's role descriptors
(effectively limited by it). An API key must have `manage_api_key` or higher privileges to retrieve the limited-by role descriptors of any API key, including itself.

`active_only`::
(Optional, Boolean) A boolean flag that can be used to query API keys that are currently active.
An API key is considered active if it is neither invalidated, nor expired at query time. You can specify this together
with other parameters such as `owner` or `name`. If `active_only` is `false`, the response will
include both active and inactive (expired or invalidated) keys. Defaults to `false`.

NOTE: When none of the parameters "id", "name", "username" and "realm_name"
are specified, and the "owner" is set to false then it will retrieve all API
keys if the user is authorized. If the user is not authorized to retrieve other user's
Expand Down Expand Up @@ -230,6 +236,13 @@ GET /_security/api_key
--------------------------------------------------
// TEST[continued]

The following example retrieves all active API keys if the user is authorized to do so:
[source,console]
--------------------------------------------------
GET /_security/api_key?active_only=true
--------------------------------------------------
// TEST[continued]

Following creates an API key

[source,console]
Expand Down

0 comments on commit ddc470c

Please sign in to comment.