Update a cross-cluster API key

  • PUT /_security/cross_cluster/api_key/{id}
Auth

Update the attributes of an existing cross-cluster API key, which is used for API key based remote cluster access.

To use this API, you must have at least the manage_security cluster privilege. Users can only update API keys that they created. To update another user's API key, use the run_as feature to submit a request on behalf of another user.

Important

It's not possible to use an API key as the authentication credential for this API. To update an API key, the owner user's credentials are required.

It's not possible to update expired API keys, or API keys that have been invalidated by the invalidate API key API.

This API supports updates to an API key's access scope, metadata, and expiration. The owner user's information, such as the username and realm, is also updated automatically on every call.

Note

This API cannot update REST API keys, which should be updated by either the update API key or bulk update API keys API.

Read the reference documentation

Required authorization

Cluster privileges manage_security

Path parameters

id string required

The ID of the cross-cluster API key to update.

Request body

access object required

The access to be granted to this API key. The access is composed of permissions for cross cluster search and cross cluster replication. At least one of them must be specified. When specified, the new access assignment fully replaces the previously assigned access.

replication object[]

A list of indices permission entries for cross-cluster replication.

names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

allow_restricted_indices boolean · default: false

This needs to be set to true if the patterns in the names field should cover system indices.

A list of indices permission entries for cross-cluster search.

field_security object

The document fields that the owners of the role have read access to.

Reference
except union oneOf
One of: string[] or string
grant union oneOf
One of: string[] or string
names union string | string[] required

A list of indices (or index name patterns) to which the permissions in this entry apply.

query union oneOf

A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.

One of:
allow_restricted_indices boolean · default: false

Set to true if using wildcard or regular expressions for patterns that cover restricted indices. Implicitly, restricted indices have limited privileges that can cause pattern tests to fail. If restricted indices are explicitly included in the names list, Elasticsearch checks privileges against these indices regardless of the value set for allow_restricted_indices.

expiration string

The expiration time for the API key. By default, API keys never expire. This property can be omitted to leave the value unchanged.

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. When specified, this information fully replaces metadata previously associated with the API key.

Response

application/json
updated boolean required

If true, the API key was updated. If false, the API key didn’t change because no change was detected.