Find API keys with a query
- POST also GET /_security/_query/api_key
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 privileges
- Cluster privileges manage_own_api_key read_security
Query parameters
-
with_limited_byboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
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_keyor higher privileges. -
with_profile_uidboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.14 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
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_uidresponse field for each API key. -
typed_keysboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.14 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Determines whether aggregation names are prefixed by their respective types in the response.
Request body
-
aggregationsmap string to object -
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. -
<string>object -
aggregationsmap string to object -
Sub-aggregations for this aggregation. Only applies to bucket aggregations.
-
cardinalityobject -
A single-value metrics aggregation that calculates an approximate count of distinct values.
-
missingboolean | number | string -
The value to apply to documents that do not have a value. By default, documents without a value are ignored.
-
precision_thresholdnumber · default: 3000 -
A unique count below which counts are expected to be close to accurate. This allows to trade memory for accuracy.
-
execution_hintenum -
Mechanism by which cardinality aggregations is run.
Supported values include:
global_ordinals: Run the aggregation by using global ordinals of the field and resolving those values after finishing a shard.segment_ordinals: Run the aggregation by using segment ordinal values and resolving those values after each segment.direct: Run the aggregation by using field values directly.save_memory_heuristic: Heuristic-based mode, default in Elasticsearch 8.3 and earlier.save_time_heuristic: Heuristic-based mode, default in Elasticsearch 8.4 and later.
-
Values:
global_ordinalssegment_ordinalsdirectsave_memory_heuristicsave_time_heuristic -
compositeobject -
A multi-bucket aggregation that creates composite buckets from different sources. Unlike the other multi-bucket aggregations, you can use the
compositeaggregation to paginate all buckets from a multi-level aggregation efficiently. -
date_rangeobject -
A multi-bucket value source based aggregation that enables the user to define a set of date ranges - each representing a bucket.
-
filterobject -
A single bucket aggregation that narrows the set of documents to those that match a query.
-
boolobject -
Matches documents matching boolean combinations of other queries.
-
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
filterunion oneOf -
The clause (query) must appear in matching documents. However, unlike
must, the score of the query will be ignored. -
One of:
Query[]orQuery -
minimum_should_matchnumber | string -
Specifies the number or percentage of
shouldclauses returned documents must match. -
mustunion oneOf -
The clause (query) must appear in matching documents and will contribute to the score.
-
One of:
Query[]orQuery -
idsobject -
Returns documents based on their IDs. This query uses document IDs stored in the
_idfield. -
matchmap string to object · min properties: 1 · max properties: 1 -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
auto_generate_synonyms_phrase_queryboolean · default: true -
If
true, match phrase queries are automatically created for multi-term synonyms. -
fuzzy_transpositionsboolean · default: true -
If
true, edits for fuzzy matching include transpositions of two adjacent characters (for example,abtoba). -
lenientboolean · default: false -
If
true, format-based errors, such as providing a text query value for a numeric field, are ignored. -
minimum_should_matchnumber | string -
Minimum number of clauses that must match for a document to be returned.
-
operatorenum · default: 'or' -
Boolean logic used to interpret text in the query value.
-
Values:
andANDorOR -
queryboolean | number | stringrequired -
Text, number, boolean value or date you wish to find in the provided field.
-
zero_terms_queryenum · default: 'none' -
Indicates whether no documents are returned if the
analyzerremoves all tokens, such as when using astopfilter.Supported values include:
all: Returns all documents, similar to amatch_allquery.none: No documents are returned if theanalyzerremoves all tokens.
-
Values:
allnone -
prefixmap string to object · min properties: 1 · max properties: 1 -
Returns documents that contain a specific prefix in a provided field.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
case_insensitiveboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Allows case insensitive matching of the value with the indexed field values when set to
true. Default isfalsewhich means the case sensitivity of matching depends on the underlying field’s mapping. -
rangemap string to oneOf · min properties: 1 · max properties: 1 -
Returns documents that contain terms within a provided range.
-
<string>union oneOf -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
simple_query_stringobject -
Returns documents based on a provided query string, using a parser with a limited but fault-tolerant syntax.
-
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
analyze_wildcardboolean · default: false -
If
true, the query attempts to analyze wildcard terms in the query string. -
auto_generate_synonyms_phrase_queryboolean · default: true -
If
true, the parser creates a match_phrase query for each multi-position token. -
default_operatorenum · default: 'or' -
Default boolean logic used to interpret text in the query string if no operators are specified.
-
Values:
andANDorOR -
fieldsstring[] -
Array of fields you wish to search. Accepts wildcard expressions. You also can boost relevance scores for matches to particular fields using a caret (
^) notation. Defaults to theindex.query.default_field indexsetting, which has a default value of*. -
flagsunion · default: ALL -
List of enabled operators for the simple query string syntax.
-
Values:
NONEANDNOTORPREFIXPHRASEPRECEDENCEESCAPEWHITESPACEFUZZYNEARSLOPALL -
fuzzy_max_expansionsnumber · default: 50 -
Maximum number of terms to which the query expands for fuzzy matching.
-
fuzzy_prefix_lengthnumber · default: 0 -
Number of beginning characters left unchanged for fuzzy matching.
-
fuzzy_transpositionsboolean -
If
true, edits for fuzzy matching include transpositions of two adjacent characters (for example,abtoba). -
lenientboolean · default: false -
If
true, format-based errors, such as providing a text value for a numeric field, are ignored. -
minimum_should_matchnumber | string -
Minimum number of clauses that must match for a document to be returned.
-
termmap string to object · min properties: 1 · max properties: 1 -
Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
valueunion oneOfrequired -
Term you wish to find in the provided field.
-
One of:
numberorstringorboolean -
case_insensitiveboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Allows case insensitive matching of the value with the indexed field values when set to
true. Whenfalse, the case sensitivity of matching depends on the underlying field’s mapping. -
termsobject -
Returns documents that contain one or more exact terms in a provided field. To return a document, one or more terms must exactly match a field value, including whitespace and capitalization.
-
wildcardmap string to object · min properties: 1 · max properties: 1 -
Returns documents that contain terms matching a wildcard pattern.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
case_insensitivebooleanThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Allows case insensitive matching of the pattern with the indexed field values when set to true. Default is false which means the case sensitivity of matching depends on the underlying field’s mapping.
-
filtersobject -
A multi-bucket aggregation where each bucket contains the documents that match a query.
-
filtersunion oneOf -
Collection of queries from which to build buckets.
- One of:
-
<string>object · min properties: 1 · max properties: 1 -
Same fields as
filterinaggregations -
boolobject -
Matches documents matching boolean combinations of other queries.
-
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
filterunion oneOf -
The clause (query) must appear in matching documents. However, unlike
must, the score of the query will be ignored. -
One of:
Query[]orQuery -
minimum_should_matchnumber | string -
Specifies the number or percentage of
shouldclauses returned documents must match. -
mustunion oneOf -
The clause (query) must appear in matching documents and will contribute to the score.
-
One of:
Query[]orQuery -
idsobject -
Returns documents based on their IDs. This query uses document IDs stored in the
_idfield. -
matchmap string to object · min properties: 1 · max properties: 1 -
Returns documents that match a provided text, number, date or boolean value. The provided text is analyzed before matching.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
auto_generate_synonyms_phrase_queryboolean · default: true -
If
true, match phrase queries are automatically created for multi-term synonyms. -
fuzzy_transpositionsboolean · default: true -
If
true, edits for fuzzy matching include transpositions of two adjacent characters (for example,abtoba). -
lenientboolean · default: false -
If
true, format-based errors, such as providing a text query value for a numeric field, are ignored. -
minimum_should_matchnumber | string -
Minimum number of clauses that must match for a document to be returned.
-
operatorenum · default: 'or' -
Boolean logic used to interpret text in the query value.
-
Values:
andANDorOR -
queryboolean | number | stringrequired -
Text, number, boolean value or date you wish to find in the provided field.
-
zero_terms_queryenum · default: 'none' -
Indicates whether no documents are returned if the
analyzerremoves all tokens, such as when using astopfilter.Supported values include:
all: Returns all documents, similar to amatch_allquery.none: No documents are returned if theanalyzerremoves all tokens.
-
Values:
allnone -
prefixmap string to object · min properties: 1 · max properties: 1 -
Returns documents that contain a specific prefix in a provided field.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
case_insensitiveboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Allows case insensitive matching of the value with the indexed field values when set to
true. Default isfalsewhich means the case sensitivity of matching depends on the underlying field’s mapping. -
rangemap string to oneOf · min properties: 1 · max properties: 1 -
Returns documents that contain terms within a provided range.
-
<string>union oneOf -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
relationenum · default: intersects -
Indicates how the range query matches values for
rangefields.Supported values include:
within: Matches documents with a range field value entirely within the query’s range.contains: Matches documents with a range field value that entirely contains the query’s range.intersects: Matches documents with a range field value that intersects the query’s range.
-
Values:
withincontainsintersects -
simple_query_stringobject -
Returns documents based on a provided query string, using a parser with a limited but fault-tolerant syntax.
-
Same fields as
simple_query_stringinfilter -
termmap string to object · min properties: 1 · max properties: 1 -
Returns documents that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
valueunion oneOfrequired -
Term you wish to find in the provided field.
-
One of:
numberorstringorboolean -
case_insensitiveboolean · default: falseThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Allows case insensitive matching of the value with the indexed field values when set to
true. Whenfalse, the case sensitivity of matching depends on the underlying field’s mapping. -
termsobject -
Returns documents that contain one or more exact terms in a provided field. To return a document, one or more terms must exactly match a field value, including whitespace and capitalization.
-
wildcardmap string to object · min properties: 1 · max properties: 1 -
Returns documents that contain terms matching a wildcard pattern.
-
<string>object -
boostnumber · default: 1 -
Floating point number used to decrease or increase the relevance scores of the query. Boost values are relative to the default value of 1.0. A boost value between 0 and 1.0 decreases the relevance score. A value greater than 1.0 increases the relevance score.
-
case_insensitivebooleanThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Allows case insensitive matching of the pattern with the indexed field values when set to true. Default is false which means the case sensitivity of matching depends on the underlying field’s mapping.
-
rangeobject -
A multi-bucket value source based aggregation that enables the user to define a set of ranges - each representing a bucket.
-
termsobject -
A multi-bucket value source based aggregation where buckets are dynamically built - one per unique value.
-
collect_modeenum -
Determines how child aggregations should be calculated: breadth-first or depth-first.
Supported values include:
depth_first: Expands all branches of the aggregation tree in one depth-first pass, before any pruning occurs.breadth_first: Caches the set of documents that fall into the uppermost buckets for subsequent replay.
-
Values:
depth_firstbreadth_first -
excludeunion oneOf -
Values to exclude. Accepts regular expressions and partitions.
-
One of:
string[]orstring -
execution_hintenum -
Determines whether the aggregation will use field values directly or global ordinals.
-
Values:
mapglobal_ordinalsglobal_ordinals_hashglobal_ordinals_low_cardinality -
min_doc_countnumber · default: 1 -
Only return values that are found in more than
min_doc_counthits. -
missingboolean | number | string -
The value to apply to documents that do not have a value. By default, documents without a value are ignored.
-
orderunion oneOf -
Specifies the sort order of the buckets. Defaults to sorting by descending document count.
-
One of:
string to enum[]orstring to enum -
shard_min_doc_countnumber -
Regulates the certainty a shard has if the term should actually be added to the candidate list or not with respect to the
min_doc_count. Terms will only be considered if their local shard frequency within the set is higher than theshard_min_doc_count. -
shard_sizenumber -
The number of candidate terms produced by each shard. By default,
shard_sizewill be automatically estimated based on the number of shards and thesizeparameter. -
queryobject -
A query to filter which API keys to return. If the query parameter is missing, it is equivalent to a
match_allquery. 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.NoteThe queryable string values associated with API keys are internally mapped as keywords. Consequently, if no
analyzerparameter is specified for amatchquery, then the provided match query string is interpreted as a single keyword value. Such a match query is hence equivalent to atermquery. -
Same fields as
filterinaggregations -
fromnumber · default: 0 -
The starting document offset. It must not be negative. By default, you cannot page through more than 10,000 hits using the
fromandsizeparameters. To page through more hits, use thesearch_afterparameter. -
sortunion oneOf -
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_docfield to sort by index order. - Reference
-
sizenumber · default: 10 -
The number of hits to return. It must not be negative. The
sizeparameter 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 thefromandsizeparameters. To page through more hits, use thesearch_afterparameter.
ApiKeyQueryContainer[]
Response
-
api_keysobject[]required -
A list of API key information.
-
typeenumrequired The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
The type of the API key (e.g.
restorcross_cluster). -
Values:
restcross_cluster -
invalidatedbooleanrequired -
Invalidation status for the API key. If the key has been invalidated, it has a value of
true. Otherwise, it isfalse. -
invalidationnumberThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.12 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
If the key has been invalidated, invalidation time in milliseconds.
-
realm_typestringThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.14 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Realm type of the principal for which this API key was created
-
metadataobjectrequired The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 7.13 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
Metadata of the API key
-
role_descriptorsmap string to object -
The role descriptors assigned to this API key when it was created or last updated. An empty role descriptor means the API key inherits the owner user’s permissions.
-
<string>object -
clusterunion anyOf[] -
A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
-
Values:
allcancel_taskclone_api_keycreate_snapshotcross_cluster_replicationcross_cluster_searchdelegate_pkigrant_api_keymanagemanage_api_keymanage_autoscalingmanage_behavioral_analyticsmanage_ccrmanage_data_frame_transformsmanage_data_stream_global_retentionmanage_enrichmanage_esqlmanage_ilmmanage_index_templatesmanage_inferencemanage_ingest_pipelinesmanage_logstash_pipelinesmanage_mlmanage_oidcmanage_own_api_keymanage_pipelinemanage_reindexmanage_rollupmanage_samlmanage_search_applicationmanage_search_query_rulesmanage_search_synonymsmanage_securitymanage_service_accountmanage_slmmanage_tokenmanage_transformmanage_user_profilemanage_watchermonitormonitor_data_frame_transformsmonitor_data_stream_global_retentionmonitor_enrichmonitor_esqlmonitor_inferencemonitor_mlmonitor_reindexmonitor_rollupmonitor_snapshotmonitor_statsmonitor_text_structuremonitor_transformmonitor_watchernonepost_behavioral_analytics_eventread_ccrread_fleet_secretsread_ilmread_pipelineread_securityread_slmtransport_clientwrite_connector_secretswrite_fleet_secrets -
indicesobject[] -
A list of indices permissions entries.
-
field_securityobject -
The document fields that the owners of the role have read access to.
- Reference
-
namesunion string | string[]required -
A list of indices (or index name patterns) to which the permissions in this entry apply.
-
privilegesunion anyOf[]required -
The index level privileges that owners of the role have on the specified indices.
-
Values:
allauto_configurecreatecreate_doccreate_indexcreate_viewcross_cluster_replicationcross_cluster_replication_internaldeletedelete_indexdelete_viewindexmaintenancemanagemanage_data_stream_lifecyclemanage_follow_indexmanage_ilmmanage_leader_indexmanage_viewmonitornonereadread_cross_clusterread_view_metadataview_index_metadatawrite -
queryunion oneOf -
A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.
- One of:
-
templateobject -
When you create a role, you can specify a query that defines the document level security permissions. You can optionally use Mustache templates in the role query to insert the username of the current authenticated user into the role. Like other places in Elasticsearch that support templating or scripting, you can specify inline, stored, or file-based templates and define custom parameters. You access the details for the current authenticated user through the _user parameter.
- Reference
-
sourceunion oneOf - One of:
-
paramsmap string to object -
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
-
langunion anyOf · default: painless -
Specifies the language the script is written in.
Supported values include:
painless: Painless scripting language, purpose-built for Elasticsearch.expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.mustache: Mustache templated, used for templates.java: Expert Java API
-
Values:
painlessexpressionmustachejava -
allow_restricted_indicesboolean · default: false -
Set to
trueif using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in thenameslist, Elasticsearch checks privileges against these indices regardless of the value set forallow_restricted_indices. -
remote_indicesobject[]The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.14 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
A list of indices permissions for remote clusters.
-
clustersunion oneOfrequired -
A list of cluster aliases to which the permissions in this entry apply.
-
One of:
string[]orstring -
field_securityobject -
The document fields that the owners of the role have read access to.
- Reference
-
namesunion string | string[]required -
A list of indices (or index name patterns) to which the permissions in this entry apply.
-
privilegesunion anyOf[]required -
The index level privileges that owners of the role have on the specified indices.
-
Values:
allauto_configurecreatecreate_doccreate_indexcreate_viewcross_cluster_replicationcross_cluster_replication_internaldeletedelete_indexdelete_viewindexmaintenancemanagemanage_data_stream_lifecyclemanage_follow_indexmanage_ilmmanage_leader_indexmanage_viewmonitornonereadread_cross_clusterread_view_metadataview_index_metadatawrite -
queryunion oneOf -
A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.
- One of:
-
templateobject -
When you create a role, you can specify a query that defines the document level security permissions. You can optionally use Mustache templates in the role query to insert the username of the current authenticated user into the role. Like other places in Elasticsearch that support templating or scripting, you can specify inline, stored, or file-based templates and define custom parameters. You access the details for the current authenticated user through the _user parameter.
- Reference
-
sourceunion oneOf - One of:
-
paramsmap string to object -
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
-
langunion anyOf · default: painless -
Specifies the language the script is written in.
Supported values include:
painless: Painless scripting language, purpose-built for Elasticsearch.expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.mustache: Mustache templated, used for templates.java: Expert Java API
-
Values:
painlessexpressionmustachejava -
allow_restricted_indicesboolean · default: false -
Set to
trueif using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in thenameslist, Elasticsearch checks privileges against these indices regardless of the value set forallow_restricted_indices. -
remote_clusterobject[]The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.15 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.
-
globalobject -
An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware.
-
profileobject -
A privilege that grants the ability to write the
dataandaccesssections of user profiles for the specified applications. -
roleobject -
A privilege that grants the ability to manage roles that are scoped to the specified indices.
-
data_sourceobject[]The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
A list of data source privilege entries, used to grant access to ES|QL data sources.
-
namesstring[]required -
A list of data source names or wildcard patterns to which the permissions in this entry apply.
-
privilegesunion anyOf[]required -
The data source privileges that owners of the role have for the specified data sources.
Supported values include:
create: Grants privilege to create a data source with a matching name.delete: Grants privilege to delete a data source with a matching name.read_metadata: Grants privilege to read a data source's metadata.read: Grants privilege to attach a dataset to a data source with a matching name.manage: Grants all data source privileges, includingcreate,delete,read, andread_metadata.
-
Values:
createdeleteread_metadatareadmanage -
metadataobject -
Optional meta-data. Within the metadata object, keys that begin with
_are reserved for system usage. -
run_asstring[] -
A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty
run_asfield, but a non-empty list will be rejected. - Reference
-
limited_bystring to object[]The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.5 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
The owner user’s permissions associated with the API key. It is a point-in-time snapshot captured at creation and subsequent updates. An API key’s effective permissions are an intersection of its assigned privileges and the owner user’s permissions.
-
accessobjectThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.10 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
The access granted to cross-cluster API keys. The access is composed of permissions for cross cluster search and cross cluster replication. At least one of them must be specified. When specified, the new access assignment fully replaces the previously assigned access.
-
searchobject[] -
A list of indices permission entries for cross-cluster search.
-
field_securityobject -
The document fields that the owners of the role have read access to.
- Reference
-
namesunion string | string[]required -
A list of indices (or index name patterns) to which the permissions in this entry apply.
-
queryunion oneOf -
A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.
- One of:
-
templateobject -
When you create a role, you can specify a query that defines the document level security permissions. You can optionally use Mustache templates in the role query to insert the username of the current authenticated user into the role. Like other places in Elasticsearch that support templating or scripting, you can specify inline, stored, or file-based templates and define custom parameters. You access the details for the current authenticated user through the _user parameter.
- Reference
-
sourceunion oneOf - One of:
-
paramsmap string to object -
Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
-
langunion anyOf · default: painless -
Specifies the language the script is written in.
Supported values include:
painless: Painless scripting language, purpose-built for Elasticsearch.expression: Lucene’s expressions language, compiles a JavaScript expression to bytecode.mustache: Mustache templated, used for templates.java: Expert Java API
-
Values:
painlessexpressionmustachejava -
allow_restricted_indicesboolean · default: false -
Set to
trueif using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in thenameslist, Elasticsearch checks privileges against these indices regardless of the value set forallow_restricted_indices. -
certificate_identitystringThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.3 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
The certificate identity associated with a cross-cluster API key. Restricts the API key to connections authenticated by a specific TLS certificate. Only applicable to cross-cluster API keys.
-
profile_uidstringThe Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 8.14 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. -
The profile uid for the API key owner principal, if requested and if it exists
-
aggregationsmap string to oneOf -
The aggregations result, if requested.
-
<string>union oneOf -
bucketsunion oneOfrequired -
Same options as
bucketsinRangeAggregate
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Query
An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
Value count aggregation result. value is always present.
Result of a terms aggregation when the field is a string.
Result of a terms aggregation when the field is some kind of whole number like a integer, long, or a date.
Result of a terms aggregation when the field is some kind of decimal number like a float, double, or distance.
Result of a terms aggregation when the field is unmapped. buckets is always empty.
Result of a date_range aggregation. Same format as a for a range aggregation: from and to
in buckets are milliseconds since the Epoch, represented as a floating point number.