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.
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.
-
global object
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.
-
indices array[object]
A list of indices permissions entries.
-
remote_indices array[object]
A list of remote 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"],"global":{"additionalProperty1":{},"additionalProperty2":{}},"indices":[{"field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"remote_indices":[{"clusters":"string","field_security":{"except":"string","grant":"string"},"names":"string","privileges":["string"],"":"string","allow_restricted_indices":true}],"metadata":{"additionalProperty1":{},"additionalProperty2":{}},"run_as":["string"],"description":"string","transient_metadata":{"additionalProperty1":{},"additionalProperty2":{}}}'
{
"applications": [
{
"application": "string",
"privileges": [
"string"
],
"resources": [
"string"
]
}
],
"cluster": [
"string"
],
"global": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"indices": [
{
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"remote_indices": [
{
"clusters": "string",
"field_security": {
"except": "string",
"grant": "string"
},
"names": "string",
"privileges": [
"string"
],
"": "string",
"allow_restricted_indices": true
}
],
"metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
},
"run_as": [
"string"
],
"description": "string",
"transient_metadata": {
"additionalProperty1": {},
"additionalProperty2": {}
}
}
{
"role": {
"created": true
}
}