Grant an API key

  • POST /_security/api_key/grant
Auth

Create an API key on behalf of another user. This API is similar to the create API keys API, however it creates the API key for a user that is different than the user that runs the API. The caller must have authentication credentials for the user on whose behalf the API key will be created. It is not possible to use this API to create an API key without that user's credentials. The supported user authentication credential types are:

  • username and password
  • Elasticsearch access tokens
  • JWTs
  • service account tokens of user-managed service accounts

The user, for whom the authentication credentials is provided, can optionally "run as" (impersonate) another user. In this case, the API key will be created on behalf of the impersonated user. Run as is not supported with the _user_managed_service_account grant type.

This API is intended be used by applications that need to create and manage API keys for end users, but cannot guarantee that those users have permission to create API keys on their own behalf. The API keys are created by the Elasticsearch API key service, which is automatically enabled.

A successful grant API key API call returns a JSON structure that contains the API key, its unique id, and its name. If applicable, it also returns expiration information for the API key in milliseconds.

By default, API keys never expire. You can specify expiration information when you create the API keys.

Required authorization

Cluster privileges grant_api_key

Query parameters

refresh enum · default: false

If 'true', Elasticsearch refreshes the affected shards to make this operation visible to search. If 'wait_for', it waits for a refresh to make this operation visible to search. If 'false', nothing is done with refreshes.

Values: true false wait_for

Request body

api_key object required

The API key.

name string required
expiration string

Expiration time for the API key. By default, API keys never expire.

role_descriptors union oneOf

The role descriptors for this API key. When it is not specified or is an empty array, the API key has a point in time snapshot of permissions of the specified user or access token. If you supply role descriptors, the resultant permissions are an intersection of API keys permissions and the permissions of the user or access token.

map string to object or [] map string to object
metadata object

Arbitrary metadata that you want to associate with the API key. It supports nested data structure. Within the metadata object, keys beginning with _ are reserved for system usage.

grant_type enum required

The type of grant. Supported grant types are: access_token, password, and _user_managed_service_account.

Supported values include:

  • access_token
  • password
  • _user_managed_service_account: In this type of grant, you must supply a service account token of a user-managed service account in the service_account_token parameter. The API key is owned by the service account and is limited by the roles assigned to it. The service account token is authenticated on every grant, so a disabled account or an invalidated token is rejected. Tokens that belong to built-in (elastic/*) service accounts are rejected.
Values: access_token password _user_managed_service_account
access_token string

The user's access token. If you specify the access_token grant type, this parameter is required. It is not valid with other grant types.

client_authentication object

The client authentication for a JWT that requires it, which is what is normally sent in the ES-Client-Authentication request header. It is valid only with the access_token grant type, when the access token is a JWT.

scheme enum required

The client authentication scheme.

Supported values include:

  • SharedSecret: The client authenticates with the shared secret configured for the JWT realm.
Values: SharedSecret
value string required

The client authentication value, which is what normally follows the scheme in the ES-Client-Authentication request header.

service_account_token string

The service account token of a user-managed service account, as returned by the create service account token API. If you specify the _user_managed_service_account grant type, this parameter is required. It is not valid with other grant types.

username string

The user name that identifies the user. If you specify the password grant type, this parameter is required. It is not valid with other grant types.

password string

The user's password. If you specify the password grant type, this parameter is required. It is not valid with other grant types.

run_as string

The name of the user to be impersonated. It is not valid with the _user_managed_service_account grant type.

Response

application/json
api_key string required
id string required
name string required
expiration number
encoded string required