Update Cross-Cluster API key API
editUpdate Cross-Cluster API key API
editUpdate an existing cross-cluster API Key that is used for API key based remote cluster access.
Request
editPUT /_security/cross_cluster/api_key/<id>
Prerequisites
edit-
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 therun_as
feature to submit a request on behalf of another user.
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.
Description
editUse this API to update cross-cluster API keys created by the Create Cross-Cluster API key API. It’s not possible to update expired API keys, or API keys that have been invalidated by invalidate API Key.
This API supports updates to an API key’s access scope, metadata and expiration.
The owner user’s information, e.g. username
, realm
, is also updated automatically on every call.
This API cannot update REST API keys, which should be updated by either Update API key or Bulk update API keys API.
Path parameters
edit-
id
- (Required, string) The ID of the API key to update.
Request body
editYou can specify the following parameters in the request body. The parameters are optional. But they cannot all be absent.
-
access
- (Optional, object) 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. Refer to the parameter of the same of the Create Cross-Cluster API key API for the field’s structure.
-
metadata
-
(Optional, object) Arbitrary metadata that you want to associate with the API key.
It supports nested data structure.
Within the
metadata
object, top-level keys beginning with_
are reserved for system usage. When specified, this fully replaces metadata previously associated with the API key. -
expiration
- (Optional, string) Expiration time for the API key. By default, API keys never expire. Can be omitted to leave unchanged.
Response body
edit-
updated
-
(boolean) If
true
, the API key was updated. Iffalse
, the API key didn’t change because no change was detected.
Examples
editIf you create a cross-cluster API key as follows:
resp = client.perform_request( "POST", "/_security/cross_cluster/api_key", headers={"Content-Type": "application/json"}, body={ "name": "my-cross-cluster-api-key", "access": { "search": [ { "names": [ "logs*" ] } ] }, "metadata": { "application": "search" } }, ) print(resp)
const response = await client.transport.request({ method: "POST", path: "/_security/cross_cluster/api_key", body: { name: "my-cross-cluster-api-key", access: { search: [ { names: ["logs*"], }, ], }, metadata: { application: "search", }, }, }); console.log(response);
POST /_security/cross_cluster/api_key { "name": "my-cross-cluster-api-key", "access": { "search": [ { "names": ["logs*"] } ] }, "metadata": { "application": "search" } }
A successful call returns a JSON structure that provides API key information. For example:
{ "id": "VuaCfGcBCdbkQm-e5aOx", "name": "my-cross-cluster-api-key", "api_key": "ui2lp2axTNmsyakw9tvNnw", "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" }
Information of the API key, including its exact role descriptor can be inspected with the Get API key API
resp = client.security.get_api_key( id="VuaCfGcBCdbkQm-e5aOx", ) print(resp)
const response = await client.security.getApiKey({ id: "VuaCfGcBCdbkQm-e5aOx", }); console.log(response);
GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx
A successful call returns a JSON structure that contains the information of the API key:
{ "api_keys": [ { "id": "VuaCfGcBCdbkQm-e5aOx", "name": "my-cross-cluster-api-key", "type": "cross_cluster", "creation": 1548550550158, "expiration": null, "invalidated": false, "username": "myuser", "realm": "native1", "metadata": { "application": "search" }, "role_descriptors": { "cross_cluster": { "cluster": [ "cross_cluster_search" ], "indices": [ { "names": [ "logs*" ], "privileges": [ "read", "read_cross_cluster", "view_index_metadata" ], "allow_restricted_indices": false } ], "applications": [ ], "run_as": [ ], "metadata": { }, "transient_metadata": { "enabled": true } } }, "access": { "search": [ { "names": [ "logs*" ], "allow_restricted_indices": false } ] } } ] }
Role descriptor corresponding to the specified |
|
The |
The following example updates the API key created above, assigning it new access scope and metadata:
resp = client.perform_request( "PUT", "/_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx", headers={"Content-Type": "application/json"}, body={ "access": { "replication": [ { "names": [ "archive" ] } ] }, "metadata": { "application": "replication" } }, ) print(resp)
const response = await client.transport.request({ method: "PUT", path: "/_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx", body: { access: { replication: [ { names: ["archive"], }, ], }, metadata: { application: "replication", }, }, }); console.log(response);
PUT /_security/cross_cluster/api_key/VuaCfGcBCdbkQm-e5aOx { "access": { "replication": [ { "names": ["archive"] } ] }, "metadata": { "application": "replication" } }
A successful call returns a JSON structure indicating that the API key was updated:
{ "updated": true }
The API key’s permissions after the update can be inspected again with the Get API key API and it will be:
{ "api_keys": [ { "id": "VuaCfGcBCdbkQm-e5aOx", "name": "my-cross-cluster-api-key", "type": "cross_cluster", "creation": 1548550550158, "expiration": null, "invalidated": false, "username": "myuser", "realm": "native1", "metadata": { "application": "replication" }, "role_descriptors": { "cross_cluster": { "cluster": [ "cross_cluster_replication" ], "indices": [ { "names": [ "archive*" ], "privileges": [ "cross_cluster_replication", "cross_cluster_replication_internal" ], "allow_restricted_indices": false } ], "applications": [ ], "run_as": [ ], "metadata": { }, "transient_metadata": { "enabled": true } } }, "access": { "replication": [ { "names": [ "archive*" ], "allow_restricted_indices": false } ] } } ] }