Bulk update API keys

  • POST /_security/api_key/_bulk_update
Auth

Update the attributes for multiple API keys.

Important

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

This API is similar to the update API key API but enables you to apply the same update to multiple API keys in one API call. This operation can greatly improve performance over making individual updates.

It is not possible to update expired or invalidated API keys.

This API supports updates to API key access scope, metadata and expiration. The access scope of each API key is derived from the role_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 specify role_descriptors in the request, a call to this API might still change an 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.

A successful request returns a JSON structure that contains the IDs of all updated API keys, the IDs of API keys that already had the requested changes and did not require an update, and error details for any failed update.

Required authorization

Cluster privileges manage_own_api_key

Request body

expiration string

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

ids union string | string[] required

The API key identifiers.

metadata object

Arbitrary nested metadata to associate with the API keys. Within the metadata object, top-level keys beginning with an underscore (_) are reserved for system usage. Any information specified with this parameter fully replaces metadata previously associated with the API key.

role_descriptors map string to object

The role descriptors to assign to the API keys. An 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, supply the role_descriptors parameter as 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 the role_descriptors parameter. The structure of a role descriptor is the same as the request for the create API keys API.

<string> object
cluster union anyOf[]

A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

Values: all cancel_task clone_api_key create_snapshot cross_cluster_replication cross_cluster_search delegate_pki grant_api_key manage manage_api_key manage_autoscaling manage_behavioral_analytics
indices object[]

A list of indices permissions entries.

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.

privileges union anyOf[] required

The index level privileges that owners of the role have on the specified indices.

Values: all auto_configure create create_doc create_index create_view cross_cluster_replication cross_cluster_replication_internal delete delete_index delete_view index
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.

remote_indices object[]

A list of indices permissions for remote clusters.

clusters union oneOf required

A list of cluster aliases to which the permissions in this entry apply.

One of: string[] or string
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.

privileges union anyOf[] required

The index level privileges that owners of the role have on the specified indices.

Values: all auto_configure create create_doc create_index create_view cross_cluster_replication cross_cluster_replication_internal delete delete_index delete_view index
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.

remote_cluster object[]

A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

clusters union oneOf required

A list of cluster aliases to which the permissions in this entry apply.

One of: string[] or string
privileges enum[] required

The cluster level privileges that owners of the role have on the remote cluster.

Values: monitor_enrich monitor_stats
global object

An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware.

application object
manage object

The applications for which application privileges can be managed. Absent when the application section is present but grants no privileges.

applications string[] required
profile object

A privilege that grants the ability to write the data and access sections of user profiles for the specified applications.

write object

The applications for which user profile data can be written. Absent when the profile section is present but grants no privileges.

applications string[] required
role object

A privilege that grants the ability to manage roles that are scoped to the specified indices.

manage object

The index-scoped role management privileges. Absent when the role section is present but grants no privileges.

indices object[] required
names string[] required

A list of indices (or index name patterns) that the owners of the role can manage roles for.

privileges string[] required

The index privileges that the managed roles are allowed to grant on the specified indices.

data_source object[]

A list of data source privilege entries, used to grant access to ES|QL data sources.

names string[] required

A list of data source names or wildcard patterns to which the permissions in this entry apply.

privileges union anyOf[] required

The data source privileges that owners of the role have for the specified data sources.

Supported values include:

  • create: Grants privilege to create a data source with a matching name.
  • delete: Grants privilege to delete a data source with a matching name.
  • read_metadata: Grants privilege to read a data source's metadata.
  • read: Grants privilege to attach a dataset to a data source with a matching name.
  • manage: Grants all data source privileges, including create, delete, read, and read_metadata.
Values: create delete read_metadata read manage
applications object[]

A list of application privilege entries

application string required

The name of the application to which this entry applies.

privileges string[] required

A list of strings, where each element is the name of an application privilege or action.

resources string[] required

A list resources to which the privileges are applied.

metadata object

Optional meta-data. Within the metadata object, keys that begin with _ are reserved for system usage.

run_as 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 empty run_as field, but a non-empty list will be rejected.

Reference
description string

Optional description of the role descriptor

restriction object

Restriction for when the role descriptor is allowed to be effective.

workflows union anyOf[] 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.

Values: search_application_query
transient_metadata map string to object

Response

application/json
errors object
count number required

The number of errors

details map string to object required

Details about the errors, keyed by role name

<string> object
type string required

The type of error

reason union string nullable

A human-readable explanation of the error, in English.

One of: string
stack_trace string

The server stack trace. Present only if the error_trace=true parameter was sent with the request.

caused_by object
root_cause object[]
suppressed object[]
noops string[] required
updated string[] required