This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« Enroll Node API Get application privileges API »
Elastic Docs ›Elasticsearch Guide [8.x] ›REST APIs ›Security APIs

Get API key information API

edit

Get API key information API

edit

Retrieves information for one or more API keys.

Request

edit

GET /_security/api_key

Prerequisites

edit

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

      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.

Description

edit

The information for the API keys created by create API Key can be retrieved using this API.

Path parameters

edit

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 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.
with_profile_uid
(Optional, boolean) Determines whether to also retrieve the user profile uid, for the API key owner user. If it exists, the profile uid is returned under the profile_uid response field for each API key. Defaults to false.
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.

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.

Examples

edit

If you create an API key as follows:

resp = client.security.create_api_key(
    name="my-api-key",
    role_descriptors={},
    metadata={
        "application": "myapp"
    },
)
print(resp)
const response = await client.security.createApiKey({
  name: "my-api-key",
  role_descriptors: {},
  metadata: {
    application: "myapp",
  },
});
console.log(response);
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:

{
  "id":"VuaCfGcBCdbkQm-e5aOx",
  "name":"my-api-key",
  "api_key":"ui2lp2axTNmsyakw9tvNnw",
  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
}

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

resp = client.security.get_api_key(
    id="VuaCfGcBCdbkQm-e5aOx",
    with_limited_by=True,
)
print(resp)
const response = await client.security.getApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
  with_limited_by: "true",
});
console.log(response);
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&with_limited_by=true

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

{
  "api_keys": [ 
    {
      "id": "VuaCfGcBCdbkQm-e5aOx", 
      "name": "my-api-key", 
      "creation": 1548550550158, 
      "expiration": 1548551550158, 
      "invalidated": false, 
      "username": "myuser", 
      "realm": "native1", 
      "realm_type": "native",
      "metadata": { 
        "application": "myapp"
      },
      "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
            }
          }
        }
      ]
    }
  ]
}

The list of API keys that were retrieved for this request.

Id for the API key

Name of the API key

Creation time for the API key in milliseconds

Optional expiration time for the API key in milliseconds

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.

Principal for which this API key was created

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

Metadata of the API key

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.

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.

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

resp = client.security.get_api_key(
    name="my-api-key",
)
print(resp)
const response = await client.security.getApiKey({
  name: "my-api-key",
});
console.log(response);
GET /_security/api_key?name=my-api-key

API key name supports prefix search by using wildcard:

resp = client.security.get_api_key(
    name="my-*",
)
print(resp)
const response = await client.security.getApiKey({
  name: "my-*",
});
console.log(response);
GET /_security/api_key?name=my-*

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

resp = client.security.get_api_key(
    realm_name="native1",
)
print(resp)
const response = await client.security.getApiKey({
  realm_name: "native1",
});
console.log(response);
GET /_security/api_key?realm_name=native1

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

resp = client.security.get_api_key(
    username="myuser",
)
print(resp)
const response = await client.security.getApiKey({
  username: "myuser",
});
console.log(response);
GET /_security/api_key?username=myuser

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

resp = client.security.get_api_key(
    owner=True,
)
print(resp)
const response = await client.security.getApiKey({
  owner: "true",
});
console.log(response);
GET /_security/api_key?owner=true

The following example retrieves all API keys if the user is authorized to do so:

resp = client.security.get_api_key()
print(resp)
const response = await client.security.getApiKey();
console.log(response);
GET /_security/api_key

The following example retrieves all active API keys if the user is authorized to do so:

resp = client.security.get_api_key(
    active_only=True,
)
print(resp)
const response = await client.security.getApiKey({
  active_only: "true",
});
console.log(response);
GET /_security/api_key?active_only=true

Following creates an API key

resp = client.security.create_api_key(
    name="my-api-key-1",
    metadata={
        "application": "my-application"
    },
)
print(resp)
const response = await client.security.createApiKey({
  name: "my-api-key-1",
  metadata: {
    application: "my-application",
  },
});
console.log(response);
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:

resp = client.security.get_api_key(
    id="VuaCfGcBCdbkQm-e5aOx",
    owner=True,
)
print(resp)
const response = await client.security.getApiKey({
  id: "VuaCfGcBCdbkQm-e5aOx",
  owner: "true",
});
console.log(response);
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true

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

resp = client.security.get_api_key(
    username="myuser",
    realm_name="native1",
)
print(resp)
const response = await client.security.getApiKey({
  username: "myuser",
  realm_name: "native1",
});
console.log(response);
GET /_security/api_key?username=myuser&realm_name=native1

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

{
  "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": { }
    }
  ]
}
« Enroll Node API Get application privileges API »