IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Create Cross-Cluster API key API Snapshot and restore APIs »
Elastic Docs ›Elasticsearch Guide [8.15] ›REST APIs ›Security APIs

Update Cross-Cluster API key API

edit

Update Cross-Cluster API key API

edit

Update an existing cross-cluster API Key that is used for API key based remote cluster access.

Request

edit

PUT /_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 the run_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

edit

Use 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

edit

You 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. If false, the API key didn’t change because no change was detected.

Examples

edit

If 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 access scope at creation time. In this example, it grants cross cluster search permission for the logs* index pattern.

The access corresponds to the value specified at API key creation time.

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
          }
        ]
      }
    }
  ]
}

Role descriptor is updated to be the access scope specified at update time. In this example, it is updated to grant the cross cluster replication permission for the archive* index pattern.

The access corresponds to the value specified at API key update time.
« Create Cross-Cluster API key API Snapshot and restore APIs »