You're viewing version 3.8 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Patch Roles API
Introduced 1.0
Updates roles without replacing them. Specify a role name to update individual attributes of one role, or omit the role name to create, update, or delete multiple roles in a single call.
Endpoints
PATCH /_plugins/_security/api/roles
PATCH /_plugins/_security/api/roles/{role}
Path parameters
The following table lists the available path parameters.
| Parameter | Data type | Required | Description |
|---|---|---|---|
role | String | No | The name of the role to update. If omitted, the request can modify multiple roles. |
Request body fields
The request body is required. It is an array of JSON objects. Each object contains the following fields.
| Field | Data type | Description | Required |
|---|---|---|---|
op | String | The operation to perform. Valid values are add, remove, replace, move, copy, and test. | Yes |
path | String | The path to modify. When you specify a role name, the path is relative to that role, such as /index_permissions/0/fls. When you omit the role name, the path begins with the role name, such as /reporting-role/cluster_permissions. | Yes |
value | Object | The new value. Required for the add, replace, and test operations. | No |
Use - as an array index to append a new permission to the end of an array of permissions.
Example request
The following request replaces the field-level security settings of the test-role role and removes its document-level security settings:
PATCH _plugins/_security/api/roles/test-role
[
{
"op": "replace", "path": "/index_permissions/0/fls", "value": ["myfield1", "myfield2"]
},
{
"op": "remove", "path": "/index_permissions/0/dls"
}
]
The following request adds the reporting-role role and removes the test-role-2 role:
PATCH _plugins/_security/api/roles
[
{
"op": "add",
"path": "/reporting-role",
"value": {
"cluster_permissions": [
"cluster_composite_ops"
]
}
},
{
"op": "remove",
"path": "/test-role-2"
}
]
Example response
A request that updates one role names it in the response:
{
"status": "OK",
"message": "'test-role' updated."
}
A bulk request does not name the roles it changed:
{
"status": "OK",
"message": "Resource updated."
}