Find API keys with a query
Generally available
All methods and paths for this operation:
Get a paginated list of API keys and their information. You can optionally filter the results with a query.
To use this API, you must have at least the manage_own_api_key
or the read_security
cluster privileges.
If you have only the manage_own_api_key
privilege, this API returns only the API keys that you own.
If you have the read_security
, manage_api_key
, or greater privileges (including manage_security
), this API returns all API keys regardless of ownership.
Refer to the linked documentation for examples of how to find API keys:
Required authorization
- Cluster privileges:
manage_own_api_key
,read_security
Query parameters
-
Return the snapshot of the owner user's role descriptors associated with the API key. An API key's actual permission is the intersection of its assigned role descriptors and the owner user's role descriptors (effectively limited by it). An API key cannot retrieve any API key’s limited-by role descriptors (including itself) unless it has
manage_api_key
or higher privileges. -
Determines whether to also retrieve the profile UID for the API key owner principal. If it exists, the profile UID is returned under the
profile_uid
response field for each API key. -
Determines whether aggregation names are prefixed by their respective types in the response.
Body
-
Any aggregations to run over the corpus of returned API keys. Aggregations and queries work together. Aggregations are computed only on the API keys that match the query. This supports only a subset of aggregation types, namely:
terms
,range
,date_range
,missing
,cardinality
,value_count
,composite
,filter
, andfilters
. Additionally, aggregations only run over the same subset of fields that query works with. -
A query to filter which API keys to return. If the query parameter is missing, it is equivalent to a
match_all
query. The query supports a subset of query types, includingmatch_all
,bool
,term
,terms
,match
,ids
,prefix
,wildcard
,exists
,range
, andsimple_query_string
. You can query the following public information associated with an API key:id
,type
,name
,creation
,expiration
,invalidated
,invalidation
,username
,realm
, andmetadata
.NOTE: The queryable string values associated with API keys are internally mapped as keywords. Consequently, if no
analyzer
parameter is specified for amatch
query, then the provided match query string is interpreted as a single keyword value. Such a match query is hence equivalent to aterm
query. -
The starting document offset. It must not be negative. By default, you cannot page through more than 10,000 hits using the
from
andsize
parameters. To page through more hits, use thesearch_after
parameter.Default value is
0
. sort
string | object | array[string | object] The sort definition. Other than
id
, all public fields of an API key are eligible for sorting. In addition, sort can also be applied to the_doc
field to sort by index order.One of: The sort definition. Other than
id
, all public fields of an API key are eligible for sorting. In addition, sort can also be applied to the_doc
field to sort by index order.The sort definition. Other than
id
, all public fields of an API key are eligible for sorting. In addition, sort can also be applied to the_doc
field to sort by index order.-
The number of hits to return. It must not be negative. The
size
parameter can be set to0
, in which case no API key matches are returned, only the aggregation results. By default, you cannot page through more than 10,000 hits using thefrom
andsize
parameters. To page through more hits, use thesearch_after
parameter.Default value is
10
. -
The search after definition.
GET /_security/_query/api_key?with_limited_by=true
{
"query": {
"ids": {
"values": [
"VuaCfGcBCdbkQm-e5aOx"
]
}
}
}
resp = client.security.query_api_keys(
with_limited_by=True,
query={
"ids": {
"values": [
"VuaCfGcBCdbkQm-e5aOx"
]
}
},
)
const response = await client.security.queryApiKeys({
with_limited_by: "true",
query: {
ids: {
values: ["VuaCfGcBCdbkQm-e5aOx"],
},
},
});
response = client.security.query_api_keys(
with_limited_by: "true",
body: {
"query": {
"ids": {
"values": [
"VuaCfGcBCdbkQm-e5aOx"
]
}
}
}
)
$resp = $client->security()->queryApiKeys([
"with_limited_by" => "true",
"body" => [
"query" => [
"ids" => [
"values" => array(
"VuaCfGcBCdbkQm-e5aOx",
),
],
],
],
]);
curl -X GET -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"ids":{"values":["VuaCfGcBCdbkQm-e5aOx"]}}}' "$ELASTICSEARCH_URL/_security/_query/api_key?with_limited_by=true"
client.security().queryApiKeys(q -> q
.query(qu -> qu
.ids(i -> i
.values("VuaCfGcBCdbkQm-e5aOx")
)
)
.withLimitedBy(true)
);
{
"query": {
"ids": {
"values": [
"VuaCfGcBCdbkQm-e5aOx"
]
}
}
}
{
"query": {
"bool": {
"must": [
{
"prefix": {
"name": "app1-key-"
}
},
{
"term": {
"invalidated": "false"
}
}
],
"must_not": [
{
"term": {
"name": "app1-key-01"
}
}
],
"filter": [
{
"wildcard": {
"username": "org-*-user"
}
},
{
"term": {
"metadata.environment": "production"
}
}
]
}
},
"from": 20,
"size": 10,
"sort": [
{ "creation": { "order": "desc", "format": "date_time" } },
"name"
]
}
{
"query": {
"term": {
"name": {
"value": "application-key-1"
}
}
}
}
{
"api_keys": [
{
"id": "VuaCfGcBCdbkQm-e5aOx",
"name": "application-key-1",
"creation": 1548550550158,
"expiration": 1548551550158,
"invalidated": false,
"username": "myuser",
"realm": "native1",
"realm_type": "native",
"metadata": {
"application": "my-application"
},
"role_descriptors": { },
"limited_by": [
{
"role-power-user": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"*"
],
"privileges": [
"read"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
}
]
}
]
}
{
"total": 100,
"count": 10,
"api_keys": [
{
"id": "CLXgVnsBOGkf8IyjcXU7",
"name": "app1-key-79",
"creation": 1629250154811,
"invalidated": false,
"username": "org-admin-user",
"realm": "native1",
"metadata": {
"environment": "production"
},
"role_descriptors": { },
"_sort": [
"2021-08-18T01:29:14.811Z",
"app1-key-79"
]
},
{
"id": "BrXgVnsBOGkf8IyjbXVB",
"name": "app1-key-78",
"creation": 1629250153794,
"invalidated": false,
"username": "org-admin-user",
"realm": "native1",
"metadata": {
"environment": "production"
},
"role_descriptors": { },
"_sort": [
"2021-08-18T01:29:13.794Z",
"app1-key-78"
]
}
]
}
{
"total": 3,
"count": 3,
"api_keys": [
{
"id": "nkvrGXsB8w290t56q3Rg",
"name": "my-api-key-1",
"creation": 1628227480421,
"expiration": 1629091480421,
"invalidated": false,
"username": "elastic",
"realm": "reserved",
"realm_type": "reserved",
"metadata": {
"letter": "a"
},
"role_descriptors": {
"role-a": {
"cluster": [
"monitor"
],
"indices": [
{
"names": [
"index-a"
],
"privileges": [
"read"
],
"allow_restricted_indices": false
}
],
"applications": [ ],
"run_as": [ ],
"metadata": { },
"transient_metadata": {
"enabled": true
}
}
}
},
{
"id": "oEvrGXsB8w290t5683TI",
"name": "my-api-key-2",
"creation": 1628227498953,
"expiration": 1628313898953,
"invalidated": false,
"username": "elastic",
"realm": "reserved",
"metadata": {
"letter": "b"
},
"role_descriptors": { }
}
]
}