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 authorization

Cluster privileges: manage_own_api_key,read_security

About query API key information

Query Parameters

Request

Response

application/json

Examples

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

Request Console 1 / 8 languages

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

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

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.

Request Console 1 / 2 languages

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

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

Response

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

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

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

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"
      }
    }
  }
}'

Response

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

Query Parameters { with_limited_by , with_profile_uid , typed_keys , }

Request { aggregations , query , from , sort , size , search_after , }

Response

Query Parameters

Request