[role="xpack"]
[[security-api-get-api-key]]
=== Get API Key information API
++++
<titleabbrev>Get API key information</titleabbrev>
++++

Retrieves information for one or more API keys.

==== Request

`GET /_security/api_key`

==== Description

The information for the API keys created by <<security-api-create-api-key,create API Key>> can be retrieved
using this API.

==== Request Body

The following parameters can be specified in the query parameters of a GET request and
pertain to retrieving api keys:

`id` (optional)::
(string) An API key id. This parameter cannot be used with any of `name`, `realm_name` or
         `username` are used.

`name` (optional)::
(string) An API key name. This parameter cannot be used with any of `id`, `realm_name` or
                          `username` are used.

`realm_name` (optional)::
(string) The name of an authentication realm. This parameter cannot be used with either `id` or `name`.

`username` (optional)::
(string) The username of a user. This parameter cannot be used with either `id` or `name`.

NOTE: While all parameters are optional, at least one of them is required.

==== Examples

The following example to retrieve the API key identified by specified `id`:

[source,js]
--------------------------------------------------
GET /_security/api_key?id=dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==
--------------------------------------------------
// NOTCONSOLE

whereas the following example to retrieve the API key identified by specified `name`:

[source,js]
--------------------------------------------------
GET /_security/api_key?name=hadoop_myuser_key
--------------------------------------------------
// NOTCONSOLE

The following example retrieves all API keys for the `native1` realm:

[source,js]
--------------------------------------------------
GET /_xpack/api_key?realm_name=native1
--------------------------------------------------
// NOTCONSOLE

The following example retrieves all API keys for the user `myuser` in all realms:

[source,js]
--------------------------------------------------
GET /_xpack/api_key?username=myuser
--------------------------------------------------
// NOTCONSOLE

Finally, the following example retrieves all API keys for the user `myuser` in
 the `native1` realm immediately:

[source,js]
--------------------------------------------------
GET /_xpack/api_key?username=myuser&realm_name=native1
--------------------------------------------------
// NOTCONSOLE

A successful call returns a JSON structure that contains the information of one or more API keys that were retrieved.

[source,js]
--------------------------------------------------
{
  "api_keys": [ <1>
    {
      "id": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", <2>
      "name": "hadoop_myuser_key", <3>
      "creation": 1548550550158, <4>
      "expiration": 1548551550158, <5>
      "invalidated": false, <6>
      "username": "myuser", <7>
      "realm": "native1" <8>
    },
    {
      "id": "api-key-id-2",
      "name": "api-key-name-2",
      "creation": 1548550550158,
      "invalidated": false,
      "username": "user-y",
      "realm": "realm-2"
    }
  ]
}
--------------------------------------------------
// NOTCONSOLE

<1> The list of API keys that were retrieved for this request.
<2> Id for the API key
<3> Name of the API key
<4> Creation time for the API key in milliseconds
<5> optional expiration time for the API key in milliseconds
<6> invalidation status for the API key, `true` if the key has been invalidated else `false`
<7> principal for which this API key was created
<8> realm name of the principal for which this API key was created