Add docs for QueryApiKey API #76521
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,258 @@ | ||
| [role="xpack"] | ||
| [[security-api-query-api-key]] | ||
| === Query API key information API | ||
| ++++ | ||
| <titleabbrev>Query API key information</titleabbrev> | ||
| ++++ | ||
|
|
||
| Retrieves information for API keys with <<query-dsl,Query DSL>> | ||
| in a <<paginate-search-results,pagniated>> fashion. | ||
ywangd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| [[security-api-query-api-key-request]] | ||
| ==== {api-request-title} | ||
|
|
||
| `GET /_security/_query/api_key` | ||
|
|
||
| `POST /_security/_query/api_key` | ||
|
|
||
| [[security-api-query-api-key-prereqs]] | ||
| ==== {api-prereq-title} | ||
|
|
||
| * To use this API, you must have at least the `manage_own_api_key` cluster privilege. | ||
|
|
||
| [[security-api-query-api-key-desc]] | ||
| ==== {api-description-title} | ||
|
|
||
| The information for the API keys created by | ||
| <<security-api-create-api-key,create API Key>> can be retrieved using this API in | ||
| a paginated manner and optionally filtered with a query. | ||
ywangd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| [[security-api-query-api-key-request-body]] | ||
| ==== {api-path-body-title} | ||
ywangd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The following parameters can be specified in the body of a request and | ||
| pertain to retrieving api keys: | ||
ywangd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| `query`:: | ||
| (Optional, string) A <<query-dsl,query>> to filter API keys to be returned. | ||
| Note it only support a subset of the query types including | ||
| <<query-dsl-match-all-query>>, <<query-dsl-bool-query>>, | ||
| <<query-dsl-term-query>>, <<query-dsl-terms-query>>, <<query-dsl-ids-query>>, | ||
| <<query-dsl-prefix-query>>, <<query-dsl-wildcard-query>>, <<query-dsl-range-query>>. | ||
|
There was a problem hiding this comment. Should we have some comments about the fields that can be queried? Maybe a list, or at least an explanation of how people would work out what the fields are. There was a problem hiding this comment. Thanks. I added a list to explain the available fields.
ywangd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=from] | ||
| + | ||
| By default, you cannot page through more than 10,000 hits using the `from` and | ||
| `size` parameters. To page through more hits, use the | ||
| <<search-after,`search_after`>> parameter. | ||
|
|
||
| `size`:: | ||
| (Optional, integer) The number of hits to return. Needs to be non-negative. | ||
ywangd marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| + | ||
| By default, you cannot page through more than 10,000 hits using the `from` and | ||
| `size` parameters. To page through more hits, use the | ||
| <<search-after,`search_after`>> parameter. | ||
|
There was a problem hiding this comment. This is repeated from above. Is that intentional? There was a problem hiding this comment. Yes it is indeed intentional. The same is repeated on the Search API doc page. The difference is that the two parameters, |
||
|
|
||
| `sort`:: | ||
| (Optional, object) <<sort-search-results,Sort definition>>. Other than `id`, | ||
| all fields of an API key are eligible for sorting. In addition, sort can | ||
| also be applied to the `_doc` field, which is useful for tie-breaking. | ||
|
|
||
| `search_after`:: | ||
| (Optional, array) <<search-after,Search after>> definition. | ||
|
|
||
| NOTE: If the user only has `manage_own_api_key` privilege, this API returns | ||
| only those API keys that are owned by the user. | ||
|
There was a problem hiding this comment. I think we need to state the reverse as well.
(any user? all users?) There was a problem hiding this comment. Good point. I added
? |
||
|
|
||
| [[security-api-query-api-key-response-body]] | ||
| ==== {api-response-body-title} | ||
|
|
||
| This API returns the following top level fields: | ||
|
|
||
| `total`:: | ||
| The total number of API keys found. | ||
|
|
||
| `count`:: | ||
| The number of API keys returned in the response. | ||
|
|
||
| `api_keys`:: | ||
| A list of API key information. | ||
|
|
||
| [[security-api-query-api-key-example]] | ||
| ==== {api-examples-title} | ||
|
|
||
| The following example list all API keys (assuming user has the `manage_api_key` privilege): | ||
|
|
||
| [source,console] | ||
| ------------------------------------------------------------ | ||
| GET /_security/_query/api_key | ||
| ------------------------------------------------------------ | ||
|
|
||
| A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved. | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| { | ||
| "total": 3, | ||
| "count": 3, | ||
| "api_keys": [ <1> | ||
| { | ||
| "id": "nkvrGXsB8w290t56q3Rg", <2> | ||
| "name": "my-api-key-1", <3> | ||
| "creation": 1628227480421, <4> | ||
| "expiration": 1629091480421, <5> | ||
| "invalidated": false, <6> | ||
| "username": "elastic", <7> | ||
| "realm": "reserved", <8> | ||
| "metadata": { <9> | ||
| "letter": "a" | ||
| } | ||
| }, | ||
| { | ||
| "id": "oEvrGXsB8w290t5683TI", | ||
| "name": "my-api-key-2", | ||
| "creation": 1628227498953, | ||
| "expiration": 1628313898953, | ||
| "invalidated": false, | ||
| "username": "elastic", | ||
| "realm": "reserved", | ||
| "metadata": { | ||
| "letter": "b" | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| -------------------------------------------------- | ||
| // NOTCONSOLE | ||
|
|
||
| <1> The list of API keys that were retrieved for this request. | ||
| <2> Id for the API key | ||
| <3> Name of the API key | ||
| <4> Creation time for the API key in milliseconds | ||
| <5> Optional expiration time for the API key in milliseconds | ||
| <6> Invalidation status for the API key. If the key has been invalidated, it has | ||
| a value of `true`. Otherwise, it is `false`. | ||
| <7> Principal for which this API key was created | ||
| <8> Realm name of the principal for which this API key was created | ||
| <9> Metadata of the API key | ||
|
There was a problem hiding this comment. I think that these callouts should be removed in favor of a proper definition list under the |
||
|
|
||
|
|
||
| If you create an API key as follows: | ||
|
|
||
| [source,console] | ||
| ------------------------------------------------------------ | ||
| POST /_security/api_key | ||
| { | ||
| "name": "application-key-1", | ||
| "metadata": { "application": "my-application"} | ||
| } | ||
| ------------------------------------------------------------ | ||
|
|
||
| A successful call returns a JSON structure that provides | ||
| API key information. For example: | ||
|
|
||
| [source,console-result] | ||
| -------------------------------------------------- | ||
| { | ||
| "id": "VuaCfGcBCdbkQm-e5aOx", | ||
| "name": "application-key-1", | ||
| "api_key": "ui2lp2axTNmsyakw9tvNnw" | ||
| } | ||
| -------------------------------------------------- | ||
| // TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] | ||
| // TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/] | ||
|
|
||
| You can use the following example to retrieve the API key by ID: | ||
|
|
||
| [source,console] | ||
| -------------------------------------------------- | ||
| GET /_security/_query/api_key | ||
| { | ||
| "query": { | ||
| "ids": { | ||
| "values": [ | ||
| "VuaCfGcBCdbkQm-e5aOx" | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| -------------------------------------------------- | ||
| // TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/] | ||
| // TEST[continued] | ||
|
|
||
| You can also retrieve the API key by name: | ||
|
|
||
| [source,console] | ||
| -------------------------------------------------- | ||
| GET /_security/_query/api_key | ||
| { | ||
| "query": { | ||
| "term": { | ||
| "name": { | ||
| "value": "application-key-1" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| -------------------------------------------------- | ||
| // TEST[continued] | ||
|
|
||
| You can use bool query to issue complex logical conditions and use | ||
| `from`, `size`, `sort` to help paginate the result. | ||
|
|
||
| [source,js] | ||
| -------------------------------------------------- | ||
| { | ||
| "query": { | ||
| "bool": { | ||
| "must": [ | ||
| { | ||
| "prefix": { | ||
| "name": "app1-key-" <1> | ||
| } | ||
| }, | ||
| { | ||
| "term": { | ||
| "invalidated": "false" <2> | ||
| } | ||
| } | ||
| ], | ||
| "must_not": [ | ||
| { | ||
| "term": { | ||
| "name": "app1-key-01" <3> | ||
| } | ||
| } | ||
| ], | ||
| "filter": [ | ||
| { | ||
| "wildcard": { | ||
| "username": "org-*-user" <4> | ||
| } | ||
| }, | ||
| { | ||
| "term": { | ||
| "metadata.environment": "production" <5> | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| }, | ||
| "from": 20, <6> | ||
| "size": 10, <7> | ||
| "sort": [ <8> | ||
| "creation": { "order": "desc" }, | ||
| "name" | ||
| ] | ||
| } | ||
| -------------------------------------------------- | ||
| // NOTCONSOLE | ||
|
|
||
| <1> The API key name must begin with `app1-key-` | ||
| <2> The API key must still be valid | ||
| <3> The API key name must not be `app1-key-01` | ||
| <4> The API key must be owned by username of the <<query-dsl-wildcard-query,wildcard>> pattern `org-*-user` | ||
| <5> The API key must have the metadata field `environment` that has the value of `production`. | ||
| <6> The offset to begin the search result is the 20th (zero-based index) API key | ||
| <7> The page size of the response is 10 API keys | ||
| <8> The result is first sorted by `creation` date in descending order, then by name in ascending order. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same as above.