IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Enable users API Get application privileges API »

› › ›

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_api_key cluster privilege.

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.

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:

POST /_security/api_key
{
  "name": "my-api-key",
  "role_descriptors": {}
}

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:

GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx

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

GET /_security/api_key?name=my-api-key

API key name supports prefix search by using wildcard:

GET /_security/api_key?name=my-*

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

GET /_security/api_key?realm_name=native1

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

GET /_security/api_key?username=myuser

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

GET /_security/api_key?owner=true

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

GET /_security/api_key

Following creates an API key

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:

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:

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", 
      "metadata": { 
        "application": "myapp"
      }
    },
    {
      "id": "6wHJmcQpReKBa42EHV5SBw",
      "name": "api-key-name-2",
      "creation": 1548550550158,
      "invalidated": false,
      "username": "user-y",
      "realm": "realm-2",
      "metadata": {}
    }
  ]
}

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

« Enable users API Get application privileges API »