Create or update roles
The role management APIs are generally the preferred way to manage roles in the native realm, rather than using file-based role management. The create or update roles API cannot update roles that are defined in roles files. File-based role management is not available in Elastic Serverless.
Path parameters
-
The name of the role that is being created or updated. On Elasticsearch Serverless, the role name must begin with a letter or digit and can only contain letters, digits and the characters '_', '-', and '.'. Each role must have a unique name, as this will serve as the identifier for that role.
Query parameters
-
refresh string
If
true
(the default) then refresh the affected shards to make this operation visible to search, ifwait_for
then wait for a refresh to make this operation visible to search, iffalse
then do nothing with refreshes.Values are
true
,false
, orwait_for
.
Body Required
-
applications array[object]
A list of application privilege entries.
-
cluster array[string]
A list of cluster privileges. These privileges define the cluster-level actions for users with this role.
-
indices array[object]
A list of indices permissions entries.
-
metadata object
-
run_as array[string]
A list of users that the owners of this role can impersonate. Note: in 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. -
description string
Optional description of the role descriptor
-
transient_metadata object
Indicates roles that might be incompatible with the current cluster license, specifically roles with document and field level security. When the cluster license doesn’t allow certain features for a given role, this parameter is updated dynamically to list the incompatible features. If
enabled
isfalse
, the role is ignored, but is still listed in the response from the authenticate API.
curl \
-X PUT http://api.example.com/_security/role/{name} \
-H "Content-Type: application/json" \
-d '{"applications":[{"application":"string","privileges":["string"],"resources":["string"]}],"cluster":["string"],"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string"}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}}'