Movatterモバイル変換

Update an API keyGenerally available; Added in 8.4.0

PUT /_security/api_key/{id}

Update attributes of an existing API key.This API supports updates to an API key's access scope, expiration, and metadata.

To use this API, you must have at least themanage_own_api_key cluster privilege.Users can only update API keys that they created or that were granted to them.To update another user’s API key, use therun_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. The owner user’s credentials are required.

Use this API to update API keys created by the create API key or grant API Key APIs.If you need to apply the same update to many API keys, you can use the bulk update API keys API to reduce overhead.It's not possible to update expired API keys or API keys that have been invalidated by the invalidate API key API.

The access scope of an API key is derived from therole_descriptors you specify in the request and a snapshot of the owner user's permissions at the time of the request.The snapshot of the owner's permissions is updated automatically on every call.

IMPORTANT: If you don't specifyrole_descriptors in the request, a call to this API might still change the API key's access scope.This change can occur if the owner user's permissions have changed since the API key was created or last modified.

Required authorization

Cluster privileges:manage_own_api_key

Path parameters

idstringRequired
The ID of the API key to update.

application/json

Body

role_descriptorsobject
The role descriptors to assign to this API key.The API key's effective permissions are an intersection of its assigned privileges and the point in time snapshot of permissions of the owner user.You can assign new privileges by specifying them in this parameter.To remove assigned privileges, you can supply an emptyrole_descriptors parameter, that is to say, an empty object{}.If an API key has no assigned privileges, it inherits the owner user's full permissions.The snapshot of the owner's permissions is always updated, whether you supply therole_descriptors parameter or not.The structure of a role descriptor is the same as the request for the create API keys API.
Hide role_descriptors attributeShow role_descriptors attributeobject
- *objectAdditional properties
  Hide * attributesShow * attributesobject
  clusterarray[string]
  A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.
  indicesarray[object]
  A list of indices permissions entries.
  Hide indices attributesShow indices attributesobject
  field_securityobject
  The document fields that the owners of the role have read access to.
  External documentation
  namesstring | array[string]Required
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  One of:
  IndexNamestring array-2array[string]
  privilegesarray[string]Required
  The index level privileges that owners of the role have on the specified indices.
  querystring | object
  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:
  string-1string QueryContainerobject RoleTemplateQueryobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  allow_restricted_indicesbooleanGenerally available
  Set totrue 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 thenames list, Elasticsearch checks privileges against these indices regardless of the value set forallow_restricted_indices.
  Default value isfalse.
  remote_indicesarray[object]Generally available; Added in 8.14.0
  A list of indices permissions for remote clusters.
  The subset of index level privileges that can be defined for remote clusters.
  Hide remote_indices attributesShow remote_indices attributesobject
  clustersstring | array[string]Required
  A list of cluster aliases to which the permissions in this entry apply.
  field_securityobject
  The document fields that the owners of the role have read access to.
  External documentation
  namesstring | array[string]Required
  A list of indices (or index name patterns) to which the permissions in this entry apply.
  One of:
  IndexNamestring array-2array[string]
  privilegesarray[string]Required
  The index level privileges that owners of the role have on the specified indices.
  querystring | object
  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:
  string-1string QueryContainerobject RoleTemplateQueryobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  allow_restricted_indicesbooleanGenerally available
  Set totrue 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 thenames list, Elasticsearch checks privileges against these indices regardless of the value set forallow_restricted_indices.
  Default value isfalse.
  remote_clusterarray[object]Generally available; Added in 8.15.0
  A list of cluster permissions for remote clusters.NOTE: This is limited a subset of the cluster permissions.
  The subset of cluster level privileges that can be defined for remote clusters.
  Hide remote_cluster attributesShow remote_cluster attributesobject
  clustersstring | array[string]Required
  A list of cluster aliases to which the permissions in this entry apply.
  privilegesarray[string]Required
  The cluster level privileges that owners of the role have on the remote cluster.
  Values aremonitor_enrich ormonitor_stats.
  globalarray[object] | objectGenerally available
  An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
  One of:
  array-1array[object] GlobalPrivilegeobject
  Hide attributeShow attributeobject
  applicationobjectRequired
  applicationsarray[object]
  A list of application privilege entries
  Hide applications attributesShow applications attributesobject
  applicationstringRequired
  The name of the application to which this entry applies.
  privilegesarray[string]Required
  A list of strings, where each element is the name of an application privilege or action.
  resourcesarray[string]Required
  A list resources to which the privileges are applied.
  metadataobject
  Optional meta-data. Within the metadata object, keys that begin with_ are reserved for system usage.
  Hide metadata attributeShow metadata attributeobject
  *objectAdditional properties
  run_asarray[string]
  A list of users that the API keys can impersonate.NOTE: In Elastic Cloud Serverless, the run-as feature is disabled.For API compatibility, you can still specify an emptyrun_as field, but a non-empty list will be rejected.
  descriptionstring
  Optional description of the role descriptor
  restrictionobject
  Restriction for when the role descriptor is allowed to be effective.
  Hide restriction attributeShow restriction attributeobject
  workflowsarray[string]Required
  A list of workflows to which the API key is restricted.NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.
  transient_metadataobject
  Hide transient_metadata attributeShow transient_metadata attributeobject
  *objectAdditional properties
metadataobject
Arbitrary metadata that you want to associate with the API key.It supports a nested data structure.Within the metadata object, keys beginning with_ are reserved for system usage.When specified, this value fully replaces the metadata previously associated with the API key.
Hide metadata attributeShow metadata attributeobject
- *objectAdditional properties
expirationstring
The expiration time for the API key.By default, API keys never expire.This property can be omitted to leave the expiration unchanged.
External documentation

Responses

200application/json
Hide response attributeShow response attributeobject
- updatedbooleanRequired
  Iftrue, the API key was updated.Iffalse, the API key didn't change because no change was detected.

PUT/_security/api_key/{id}

PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx{  "role_descriptors": {    "role-a": {      "indices": [        {          "names": ["*"],          "privileges": ["write"]        }      ]    }  },  "metadata": {    "environment": {      "level": 2,      "trusted": true,      "tags": ["production"]    }  }}

resp = client.security.update_api_key(    id="VuaCfGcBCdbkQm-e5aOx",    role_descriptors={        "role-a": {            "indices": [                {                    "names": [                        "*"                    ],                    "privileges": [                        "write"                    ]                }            ]        }    },    metadata={        "environment": {            "level": 2,            "trusted": True,            "tags": [                "production"            ]        }    },)

const response = await client.security.updateApiKey({  id: "VuaCfGcBCdbkQm-e5aOx",  role_descriptors: {    "role-a": {      indices: [        {          names: ["*"],          privileges: ["write"],        },      ],    },  },  metadata: {    environment: {      level: 2,      trusted: true,      tags: ["production"],    },  },});

response = client.security.update_api_key(  id: "VuaCfGcBCdbkQm-e5aOx",  body: {    "role_descriptors": {      "role-a": {        "indices": [          {            "names": [              "*"            ],            "privileges": [              "write"            ]          }        ]      }    },    "metadata": {      "environment": {        "level": 2,        "trusted": true,        "tags": [          "production"        ]      }    }  })

$resp = $client->security()->updateApiKey([    "id" => "VuaCfGcBCdbkQm-e5aOx",    "body" => [        "role_descriptors" => [            "role-a" => [                "indices" => array(                    [                        "names" => array(                            "*",                        ),                        "privileges" => array(                            "write",                        ),                    ],                ),            ],        ],        "metadata" => [            "environment" => [                "level" => 2,                "trusted" => true,                "tags" => array(                    "production",                ),            ],        ],    ],]);

curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"role_descriptors":{"role-a":{"indices":[{"names":["*"],"privileges":["write"]}]}},"metadata":{"environment":{"level":2,"trusted":true,"tags":["production"]}}}' "$ELASTICSEARCH_URL/_security/api_key/VuaCfGcBCdbkQm-e5aOx"

client.security().updateApiKey(u -> u    .id("VuaCfGcBCdbkQm-e5aOx")    .metadata("environment", JsonData.fromJson("{\"level\":2,\"trusted\":true,\"tags\":[\"production\"]}"))    .roleDescriptors("role-a", r -> r        .indices(i -> i            .names("*")            .privileges("write")        )    ));

Request examples

Run `PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx` to assign new role descriptors and metadata to an API key.

{  "role_descriptors": {    "role-a": {      "indices": [        {          "names": ["*"],          "privileges": ["write"]        }      ]    }  },  "metadata": {    "environment": {      "level": 2,      "trusted": true,      "tags": ["production"]    }  }}

Run `PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx` to remove the API key's previously assigned permissions. It will inherit the owner user's full permissions.

{  "role_descriptors": {}}

Response examples (200)

A successful response from `PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx`. The API key's effective permissions after the update will be the intersection of the supplied role descriptors and the owner user's permissions.

{  "updated": true}