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.

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Query parameters

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.
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: 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
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.
aggregations map string to oneOf: The aggregations result, if requested.

Examples

Request Console 1 / 8 languages

Run POST /_security/_query/api_key?with_limited_by=true to retrieve an API key by ID.

Console Kibana Dev Tools

POST /_security/_query/api_key?with_limited_by=true
{
  "query": {
    "ids": {
      "values": [
        "VuaCfGcBCdbkQm-e5aOx"
      ]
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.queryApiKeys({
  with_limited_by: "true",
  query: {
    ids: {
      values: ["VuaCfGcBCdbkQm-e5aOx"],
    },
  },
});

Python Elasticsearch Python Client

resp = client.security.query_api_keys(
    with_limited_by=True,
    query={
        "ids": {
            "values": [
                "VuaCfGcBCdbkQm-e5aOx"
            ]
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/_query/api_key?with_limited_by=true" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "ids": {
        "values": [
          "VuaCfGcBCdbkQm-e5aOx"
        ]
      }
    }
  }'

Java Elasticsearch Java Client

client.security().queryApiKeys(q -> q
    .query(qu -> qu
        .ids(i -> i
            .values("VuaCfGcBCdbkQm-e5aOx")
        )
    )
    .withLimitedBy(true)
);

C# Elasticsearch .NET Client

var response = await client.Security
    .QueryApiKeysAsync(d1 => d1
        .WithLimitedBy(true)
        .Query(d2 => d2
            .Ids(d3 => d3
                .Values(new[] { "VuaCfGcBCdbkQm-e5aOx" })
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->queryApiKeys([
    "with_limited_by" => "true",
    "body" => [
        "query" => [
            "ids" => [
                "values" => array(
                    "VuaCfGcBCdbkQm-e5aOx",
                ),
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.query_api_keys(
  with_limited_by: "true",
  body: {
    "query": {
      "ids": {
        "values": [
          "VuaCfGcBCdbkQm-e5aOx"
        ]
      }
    }
  }
)

Response

A successful response from GET /_security/_query/api_key?with_limited_by=true. The limited_by details are 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.

{
  "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
            }
          }
        }
      ]
    }
  ]
}

Request Console 1 / 2 languages

Run POST /_security/_query/api_key. Use a bool query to issue complex logical conditions and use from, size, and sort to help paginate the result. For example, the API key name must begin with app1-key- and must not be app1-key-01. It must be owned by a username with the wildcard pattern org-*-user and the environment metadata field must have a production value. The offset to begin the search result is the twentieth (zero-based index) API key. The page size of the response is 10 API keys. The result is first sorted by creation date in descending order, then by name in ascending order.

Console Kibana Dev Tools

POST /_security/_query/api_key
{
  "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"
  ]
}

Generated from the API spec

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/_query/api_key" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    ]
  }'

Generated from the API spec

Response

An abbreviated response from GET /_security/_query/api_key that contains a list of matched API keys along with their sort values. The first sort value is creation time, which is displayed in date_time format. The second sort value is the API key name.

{
  "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"
      ]
    }
  ]
}

Request Console 1 / 2 languages

Run POST /_security/_query/api_key to retrieve the API key by name.

Console Kibana Dev Tools

POST /_security/_query/api_key
{
  "query": {
    "term": {
      "name": {
        "value": "application-key-1"
      }
    }
  }
}

Generated from the API spec

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/_query/api_key" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "term": {
        "name": {
          "value": "application-key-1"
        }
      }
    }
  }'

Generated from the API spec

Response

A successful response from GET /_security/_query/api_key. It includes the role descriptors that are assigned to each API key when it was created or last updated. Note that an API key's effective permissions are an intersection of its assigned privileges and the point-in-time snapshot of the owner user's permissions. An empty role descriptors object means the API key inherits the owner user's permissions.

{
  "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": { } 
    }
  ]
}

Required authorization

Authentication

Query parameters

Request body { }

Response

Request body