elasticsearch/docs/reference/rest-api/security/get-api-keys.asciidoc

[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.

[[security-api-get-api-key-request]]
==== {api-request-title}

`GET /_security/api_key`

[[security-api-get-api-key-prereqs]]
==== {api-prereq-title}

* To use this API, you must have at least the `manage_own_api_key` or the
`read_security` cluster privileges.
** If you only have the `manage_own_api_key` privilege, this API only returns
the API keys that you own.
+
NOTE: Authenticating with an API key that has the `manage_own_api_key` privilege
does not allow retrieving the authenticated user's own keys. Instead,
authenticate the user with basic credentials.
** If you have `read_security`, `manage_api_key` or greater
privileges (including `manage_security`), this API returns all API keys
regardless of ownership.

[[security-api-get-api-key-desc]]
==== {api-description-title}

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

[[security-api-get-api-key-query-params]]
==== {api-path-parms-title}

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. It supports prefix search with wildcard.

`realm_name`::
(Optional, string) The name of an authentication realm. This parameter cannot be
used with either `id` or `name` or when `owner` flag is set to `true`.

`username`::
(Optional, string) The username of a user. This parameter cannot be used with
either `id` or `name` or when `owner` flag is set to `true`.

`owner`::
(Optional, Boolean) A boolean flag that can be used to query API keys owned
by the currently authenticated user. Defaults to false.
The 'realm_name' or 'username' parameters cannot be specified when this
parameter is set to 'true' as they are assumed to be the currently authenticated ones.

`with_limited_by`::
(Optional, Boolean) A boolean flag to 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 <<api-key-role-descriptors,assigned role descriptors>> and the owner user's role descriptors
(effectively limited by it). An API key must have `manage_api_key` or higher privileges to retrieve the limited-by role descriptors of any API key, including itself.

`active_only`::
(Optional, Boolean) A boolean flag that can be used to query API keys that are currently active.
An API key is considered active if it is neither invalidated, nor expired at query time. You can specify this together
with other parameters such as `owner` or `name`.  If `active_only` is `false`, the response will
include both active and inactive (expired or invalidated) keys. Defaults to `false`.

NOTE: When none of the parameters "id", "name", "username" and "realm_name"
are specified, and the "owner" is set to false then it will retrieve all API
keys if the user is authorized. If the user is not authorized to retrieve other user's
API keys, then an error will be returned.

[[security-api-get-api-key-example]]
==== {api-examples-title}

If you create an API key as follows:

[source,console]
------------------------------------------------------------
POST /_security/api_key
{
  "name": "my-api-key",
  "role_descriptors": {},
  "metadata": {
    "application": "myapp"
  }
}
------------------------------------------------------------

A successful call returns a JSON structure that provides
API key information. For example:

[source,console-result]
--------------------------------------------------
{
  "id":"VuaCfGcBCdbkQm-e5aOx",
  "name":"my-api-key",
  "api_key":"ui2lp2axTNmsyakw9tvNnw",
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}
--------------------------------------------------
// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
// TESTRESPONSE[s/VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==/$body.encoded/]

You can use the following example to retrieve the API key by ID:

[source,console]
--------------------------------------------------
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&with_limited_by=true
--------------------------------------------------
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
// TEST[continued]

A successful call returns a JSON structure that contains the information of the API key:

[source,js]
--------------------------------------------------
{
  "api_keys": [ <1>
    {
      "id": "VuaCfGcBCdbkQm-e5aOx", <2>
      "name": "my-api-key", <3>
      "creation": 1548550550158, <4>
      "expiration": 1548551550158, <5>
      "invalidated": false, <6>
      "username": "myuser", <7>
      "realm": "native1", <8>
      "realm_type": "native",
      "metadata": { <9>
        "application": "myapp"
      },
      "role_descriptors": { }, <10>
      "limited_by": [  <11>
        {
          "role-power-user": {
            "cluster": [
              "monitor"
            ],
            "indices": [
              {
                "names": [
                  "*"
                ],
                "privileges": [
                  "read"
                ],
                "allow_restricted_indices": false
              }
            ],
            "applications": [ ],
            "run_as": [ ],
            "metadata": { },
            "transient_metadata": {
              "enabled": true
            }
          }
        }
      ]
    }
  ]
}
--------------------------------------------------
// 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. If the key has been invalidated, it has
a value of `true` and an additional field with the `invalidation` time in milliseconds. Otherwise, it is `false`.
<7> Principal for which this API key was created
<8> Realm name of the principal for which this API key was created
<9> Metadata of the API key
<10> The role descriptors assigned to this API key when it was <<api-key-role-descriptors,created>>
or last <<security-api-update-api-key-api-key-role-descriptors,updated>>.
An empty role descriptor means the API key inherits the owner user's
permissions.
<11> The owner user's permissions associated with the API key.
It is a point-in-time snapshot captured at <<security-api-create-api-key,creation>> and
subsequent <<security-api-update-api-key,updates>>. An API key's
effective permissions are an intersection of its assigned privileges and
the owner user's permissions.

You can use the following example to retrieve the API key by name:

[source,console]
--------------------------------------------------
GET /_security/api_key?name=my-api-key
--------------------------------------------------
// TEST[continued]

API key name supports prefix search by using wildcard:

[source,console]
--------------------------------------------------
GET /_security/api_key?name=my-*
--------------------------------------------------
// TEST[continued]

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

[source,console]
--------------------------------------------------
GET /_security/api_key?realm_name=native1
--------------------------------------------------
// TEST[continued]

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

[source,console]
--------------------------------------------------
GET /_security/api_key?username=myuser
--------------------------------------------------
// TEST[continued]

The following example retrieves all API keys owned by the currently authenticated user:

[source,console]
--------------------------------------------------
GET /_security/api_key?owner=true
--------------------------------------------------
// TEST[continued]

The following example retrieves all API keys if the user is authorized to do so:
[source,console]
--------------------------------------------------
GET /_security/api_key
--------------------------------------------------
// TEST[continued]

The following example retrieves all active API keys if the user is authorized to do so:
[source,console]
--------------------------------------------------
GET /_security/api_key?active_only=true
--------------------------------------------------
// TEST[continued]

Following creates an API key

[source,console]
------------------------------------------------------------
POST /_security/api_key
{
  "name": "my-api-key-1",
  "metadata": {
    "application": "my-application"
  }
}
------------------------------------------------------------

The following example retrieves the API key identified by the specified `id` if
it is owned by the currently authenticated user:

[source,console]
--------------------------------------------------
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true
--------------------------------------------------
// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
// TEST[continued]

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

[source,console]
--------------------------------------------------
GET /_security/api_key?username=myuser&realm_name=native1
--------------------------------------------------
// TEST[continued]

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

[source,js]
--------------------------------------------------
{
  "api_keys": [
    {
      "id": "0GF5GXsBCXxz2eDxWwFN",
      "name": "hadoop_myuser_key",
      "creation": 1548550550158,
      "expiration": 1548551550158,
      "invalidated": false,
      "username": "myuser",
      "realm": "native1",
      "realm_type": "native",
      "metadata": {
        "application": "myapp"
      },
      "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": "6wHJmcQpReKBa42EHV5SBw",
      "name": "api-key-name-2",
      "creation": 1548550550158,
      "invalidated": false,
      "username": "user-y",
      "realm": "realm-2",
      "metadata": {},
      "role_descriptors": { }
    }
  ]
}
--------------------------------------------------
// NOTCONSOLE