Find API keys with a query

  • POST also GET /_security/_query/api_key
Auth

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:

About query API key information

Required authorization

Cluster privileges manage_own_api_key read_security

Query parameters

with_limited_by boolean · default: false

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.

with_profile_uid boolean · default: false

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.

typed_keys boolean · default: false

Determines whether aggregation names are prefixed by their respective types in the response.

Request body

aggregations map 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, and filters. Additionally, aggregations only run over the same subset of fields that query works with.

<string> object
aggregations map string to object

Sub-aggregations for this aggregation. Only applies to bucket aggregations.

meta object
cardinality object

A single-value metrics aggregation that calculates an approximate count of distinct values.

field string

The field on which to run the aggregation.

missing boolean | number | string

The value to apply to documents that do not have a value. By default, documents without a value are ignored.

script string
precision_threshold number · default: 3000

A unique count below which counts are expected to be close to accurate. This allows to trade memory for accuracy.

rehash boolean
execution_hint enum

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_ordinals segment_ordinals direct save_memory_heuristic save_time_heuristic
composite object

A multi-bucket aggregation that creates composite buckets from different sources. Unlike the other multi-bucket aggregations, you can use the composite aggregation to paginate all buckets from a multi-level aggregation efficiently.

after object

When paginating, use the after_key value returned in the previous response to retrieve the next page.

size number · default: 10

The number of composite buckets that should be returned.

sources string to object[]

The value sources used to build composite buckets. Keys are returned in the order of the sources definition.

date_range object

A multi-bucket value source based aggregation that enables the user to define a set of date ranges - each representing a bucket.

field string

The date field whose values are use to build ranges.

format string

The date format used to format from and to in the response.

missing boolean | number | string

The value to apply to documents that do not have a value. By default, documents without a value are ignored.

ranges object[]

Array of date ranges.

from union oneOf

Start of the range (inclusive).

One of: string or number
key string

Custom key to return the range with.

to union oneOf

End of the range (exclusive).

One of: string or number
time_zone string

Time zone used to convert dates from another time zone to UTC.

keyed boolean

Set to true to associate a unique string key with each bucket and returns the ranges as a hash rather than an array.

filter object

A single bucket aggregation that narrows the set of documents to those that match a query.

bool object

Matches documents matching boolean combinations of other queries.

boost number · 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.

_name string
filter union oneOf

The clause (query) must appear in matching documents. However, unlike must, the score of the query will be ignored.

One of: Query[] or Query
minimum_should_match number | string

Specifies the number or percentage of should clauses returned documents must match.

must union oneOf

The clause (query) must appear in matching documents and will contribute to the score.

One of: Query[] or Query
must_not union oneOf

The clause (query) must not appear in the matching documents. Because scoring is ignored, a score of 0 is returned for all documents.

One of: Query[] or Query
should union oneOf

The clause (query) should appear in the matching document.

One of: Query[] or Query
exists object

Returns documents that contain an indexed value for a field.

boost number · 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.

_name string
field string required

Name of the field you wish to search.

ids object

Returns documents based on their IDs. This query uses document IDs stored in the _id field.

boost number · 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.

_name string
values union oneOf

An array of document IDs.

One of: string[] or string
match map 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
boost number · 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.

_name string
analyzer string

Analyzer used to convert the text in the query value into tokens.

auto_generate_synonyms_phrase_query boolean · default: true

If true, match phrase queries are automatically created for multi-term synonyms.

cutoff_frequency number deprecated
fuzziness number | string

Maximum edit distance allowed for matching.

fuzzy_rewrite string

Method used to rewrite the query.

fuzzy_transpositions boolean · default: true

If true, edits for fuzzy matching include transpositions of two adjacent characters (for example, ab to ba).

lenient boolean · default: false

If true, format-based errors, such as providing a text query value for a numeric field, are ignored.

max_expansions number · default: 50

Maximum number of terms to which the query will expand.

minimum_should_match number | string

Minimum number of clauses that must match for a document to be returned.

operator enum · default: 'or'

Boolean logic used to interpret text in the query value.

Values: and AND or OR
prefix_length number · default: 0

Number of beginning characters left unchanged for fuzzy matching.

query boolean | number | string required

Text, number, boolean value or date you wish to find in the provided field.

zero_terms_query enum · default: 'none'

Indicates whether no documents are returned if the analyzer removes all tokens, such as when using a stop filter.

Supported values include:

  • all: Returns all documents, similar to a match_all query.
  • none: No documents are returned if the analyzer removes all tokens.
Values: all none
match_all object

Matches all documents, giving them all a _score of 1.0.

boost number · 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.

_name string
prefix map string to object · min properties: 1 · max properties: 1

Returns documents that contain a specific prefix in a provided field.

<string> object
boost number · 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.

_name string
rewrite string

Method used to rewrite the query.

value string required

Beginning characters of terms you wish to find in the provided field.

case_insensitive boolean · default: false

Allows case insensitive matching of the value 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.

range map string to oneOf · min properties: 1 · max properties: 1

Returns documents that contain terms within a provided range.

simple_query_string object

Returns documents based on a provided query string, using a parser with a limited but fault-tolerant syntax.

boost number · 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.

_name string
analyzer string

Analyzer used to convert text in the query string into tokens.

analyze_wildcard boolean · default: false

If true, the query attempts to analyze wildcard terms in the query string.

auto_generate_synonyms_phrase_query boolean · default: true

If true, the parser creates a match_phrase query for each multi-position token.

default_operator enum · default: 'or'

Default boolean logic used to interpret text in the query string if no operators are specified.

Values: and AND or OR
fields string[]

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 the index.query.default_field index setting, which has a default value of *.

flags union · default: ALL

List of enabled operators for the simple query string syntax.

Values: NONE AND NOT OR PREFIX PHRASE PRECEDENCE ESCAPE WHITESPACE FUZZY NEAR SLOP ALL
fuzzy_max_expansions number · default: 50

Maximum number of terms to which the query expands for fuzzy matching.

fuzzy_prefix_length number · default: 0

Number of beginning characters left unchanged for fuzzy matching.

fuzzy_transpositions boolean

If true, edits for fuzzy matching include transpositions of two adjacent characters (for example, ab to ba).

lenient boolean · default: false

If true, format-based errors, such as providing a text value for a numeric field, are ignored.

minimum_should_match number | string

Minimum number of clauses that must match for a document to be returned.

query string required

Query string in the simple query string syntax you wish to parse and use for search.

quote_field_suffix string

Suffix appended to quoted text in the query string.

term map 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
boost number · 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.

_name string
value union oneOf required

Term you wish to find in the provided field.

One of: number or string or boolean
case_insensitive boolean · default: false

Allows case insensitive matching of the value with the indexed field values when set to true. When false, the case sensitivity of matching depends on the underlying field’s mapping.

terms object

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.

boost number · 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.

_name string
wildcard map string to object · min properties: 1 · max properties: 1

Returns documents that contain terms matching a wildcard pattern.

<string> object
boost number · 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.

_name string
case_insensitive boolean

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.

rewrite string

Method used to rewrite the query.

value string

Wildcard pattern for terms you wish to find in the provided field. Required, when wildcard is not set.

wildcard string

Wildcard pattern for terms you wish to find in the provided field. Required, when value is not set.

filters object

A multi-bucket aggregation where each bucket contains the documents that match a query.

filters union oneOf

Collection of queries from which to build buckets.

One of:
<string> object · min properties: 1 · max properties: 1
Same fields as filter in aggregations
other_bucket boolean

Set to true to add a bucket to the response which will contain all documents that do not match any of the given filters.

other_bucket_key string · default: _other_

The key with which the other bucket is returned.

keyed boolean · default: true

By default, the named filters aggregation returns the buckets as an object. Set to false to return the buckets as an array of objects.

missing object
field string

The name of the field.

missing boolean | number | string
range object

A multi-bucket value source based aggregation that enables the user to define a set of ranges - each representing a bucket.

field string

The date field whose values are use to build ranges.

missing number

The value to apply to documents that do not have a value. By default, documents without a value are ignored.

ranges object[]

An array of ranges used to bucket documents.

from union number | string nullable

Start of the range (inclusive).

key string

Custom key to return the range with.

to union number | string nullable

End of the range (exclusive).

script string
keyed boolean

Set to true to associate a unique string key with each bucket and return the ranges as a hash rather than an array.

format string
terms object

A multi-bucket value source based aggregation where buckets are dynamically built - one per unique value.

collect_mode enum

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_first breadth_first
exclude union oneOf

Values to exclude. Accepts regular expressions and partitions.

One of: string[] or string
execution_hint enum

Determines whether the aggregation will use field values directly or global ordinals.

Values: map global_ordinals global_ordinals_hash global_ordinals_low_cardinality
field string

The field from which to return terms.

include union oneOf

Values to include. Accepts regular expressions and partitions.

One of:
string[]
min_doc_count number · default: 1

Only return values that are found in more than min_doc_count hits.

missing boolean | number | string

The value to apply to documents that do not have a value. By default, documents without a value are ignored.

missing_order enum
Values: first last default
missing_bucket boolean
value_type string

Coerced unmapped fields into the specified type.

order union oneOf

Specifies the sort order of the buckets. Defaults to sorting by descending document count.

One of: string to enum[] or string to enum
script string
shard_min_doc_count number

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 the shard_min_doc_count.

shard_size number

The number of candidate terms produced by each shard. By default, shard_size will be automatically estimated based on the number of shards and the size parameter.

show_term_doc_count_error boolean

Set to true to return the doc_count_error_upper_bound, which is an upper bound to the error on the doc_count returned by each shard.

size number · default: 10

The number of buckets returned out of the overall terms list.

format string
value_count object

A single-value metrics aggregation that counts the number of values that are extracted from the aggregated documents.

field string

The field on which to run the aggregation.

missing boolean | number | string

The value to apply to documents that do not have a value. By default, documents without a value are ignored.

script string
format string
query object

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, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple_query_string. You can query the following public information associated with an API key: id, type, name, creation, expiration, invalidated, invalidation, username, realm, and metadata.

Note

The queryable string values associated with API keys are internally mapped as keywords. Consequently, if no analyzer parameter is specified for a match query, then the provided match query string is interpreted as a single keyword value. Such a match query is hence equivalent to a term query.

Same fields as filter in aggregations
from number · default: 0

The starting document offset. It must not be negative. 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 parameter.

sort union 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 _doc field to sort by index order.

Reference
A value or an array; each item is one of:

Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

size number · default: 10

The number of hits to return. It must not be negative. The size parameter can be set to 0, 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 the from and size parameters. To page through more hits, use the search_after parameter.

search_after union[]

The search after definition.

Reference

Response

application/json
total number required

The total number of API keys found.

count number required

The number of API keys returned in the response.

api_keys object[] required

A list of API key information.

id string required

Id for the API key

name string required

Name of the API key.

type enum required

The type of the API key (e.g. rest or cross_cluster).

Values: rest cross_cluster
creation number required

Creation time for the API key in milliseconds.

expiration number

Expiration time for the API key in milliseconds.

invalidated boolean required

Invalidation status for the API key. If the key has been invalidated, it has a value of true. Otherwise, it is false.

invalidation number

If the key has been invalidated, invalidation time in milliseconds.

username string required

Principal for which this API key was created

realm string required

Realm name of the principal for which this API key was created.

realm_type string

Realm type of the principal for which this API key was created

metadata object required

Metadata of the API key

role_descriptors map 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
cluster union anyOf[]

A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

Values: all cancel_task manage manage_api_key manage_behavioral_analytics manage_enrich manage_esql manage_index_templates manage_inference manage_ingest_pipelines manage_logstash_pipelines manage_ml
indices object[]

A list of indices permissions entries.

field_security object

The document fields that the owners of the role have read access to.

Reference
except union oneOf
One of: string[] or string
grant union oneOf
One of: string[] or string
names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

privileges union anyOf[] required

The index level privileges that owners of the role have on the specified indices.

Values: all auto_configure create create_doc create_index create_view delete delete_index delete_view index maintenance manage manage_data_stream_lifecycle manage_view monitor none read read_view_metadata view_index_metadata write
query union 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:
applications object[]

A list of application privilege entries

application string required

The name of the application to which this entry applies.

privileges string[] required

A list of strings, where each element is the name of an application privilege or action.

resources string[] required

A list resources to which the privileges are applied.

metadata object

Optional meta-data. Within the metadata object, keys that begin with _ are reserved for system usage.

run_as string[]

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_as field, but a non-empty list will be rejected.

Reference
description string

Optional description of the role descriptor

restriction object

Restriction for when the role descriptor is allowed to be effective.

workflows union anyOf[] required

A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

Values: search_application_query
transient_metadata map string to object
limited_by string to object[]

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.

access object

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.

replication object[]

A list of indices permission entries for cross-cluster replication.

names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

allow_restricted_indices boolean · default: false

This needs to be set to true if the patterns in the names field should cover system indices.

A list of indices permission entries for cross-cluster search.

field_security object

The document fields that the owners of the role have read access to.

Reference
except union oneOf
One of: string[] or string
grant union oneOf
One of: string[] or string
names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

query union 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:
profile_uid string

The profile uid for the API key owner principal, if requested and if it exists

_sort union[]

Sorting values when using the sort parameter with the security.query_api_keys API.

aggregations map string to oneOf

The aggregations result, if requested.