[[role-management-api-put]]
=== Create or update role API
++++
Create or update role
++++
Create a new {kib} role, or update the attributes of an existing role. {kib} roles are stored in the
{es} native realm.
experimental["The underlying mechanism of enforcing role-based access control is stable, but the APIs for managing the roles are experimental."]
[[role-management-api-put-request]]
==== Request
`PUT /api/security/role/my_kibana_role`
[[role-management-api-put-prereqs]]
==== Prerequisite
To use the create or update role API, you must have the `manage_security` cluster privilege.
[[role-management-api-response-body]]
==== Request body
`metadata`::
(Optional, object) In the `metadata` object, keys that begin with `_` are reserved for system usage.
`elasticsearch`::
(Optional, object) {es} cluster and index privileges. Valid keys include
`cluster`, `indices`, and `run_as`. For more information, see
{ref}/defining-roles.html[Defining roles].
`kibana`::
(list) Objects that specify the <> for the role:
`base` :::
(Optional, list) A base privilege. When specified, the base must be `["all"]` or `["read"]`.
When the `base` privilege is specified, you are unable to use the `feature` section.
"all" grants read/write access to all {kib} features for the specified spaces.
"read" grants read-only access to all {kib} features for the specified spaces.
`feature` :::
(object) Contains privileges for specific features.
When the `feature` privileges are specified, you are unable to use the `base` section.
To retrieve a list of available features, use the <>.
`spaces` :::
(list) The spaces to apply the privileges to.
To grant access to all spaces, set to `["*"]`, or omit the value.
[[role-management-api-put-response-codes]]
==== Response code
`204`::
Indicates a successful call.
===== Examples
Grant access to various features in all spaces:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": [],
"feature": {
"discover": [
"all"
],
"visualize": [
"all"
],
"dashboard": [
"all"
],
"dev_tools": [
"read"
],
"advancedSettings": [
"read"
],
"indexPatterns": [
"read"
],
"timelion": [
"all"
],
"graph": [
"all"
],
"apm": [
"read"
],
"maps": [
"read"
],
"canvas": [
"read"
],
"infrastructure": [
"all"
],
"logs": [
"all"
],
"uptime": [
"all"
]
},
"spaces": [
"*"
]
}
]
}
--------------------------------------------------
// KIBANA
Grant dashboard-only access to only the Marketing space:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": [],
"feature": {
"dashboard": ["read"]
},
"spaces": [
"marketing"
]
}
]
}
--------------------------------------------------
// KIBANA
Grant full access to all features in the Default space:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": ["all"],
"feature": {
},
"spaces": [
"default"
]
}
]
}
--------------------------------------------------
// KIBANA
Grant different access to different spaces:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
"cluster" : [ ],
"indices" : [ ]
},
"kibana": [
{
"base": [],
"feature": {
"discover": ["all"],
"dashboard": ["all"]
},
"spaces": [
"default"
]
},
{
"base": ["read"],
"spaces": [
"marketing",
"sales"
]
}
]
}
--------------------------------------------------
// KIBANA
Grant access to {kib} and Elasticsearch:
[source,js]
--------------------------------------------------
PUT /api/security/role/my_kibana_role
{
"metadata" : {
"version" : 1
},
"elasticsearch": {
"cluster" : [ "all" ],
"indices" : [ {
"names" : [ "index1", "index2" ],
"privileges" : [ "all" ],
"field_security" : {
"grant" : [ "title", "body" ]
},
"query" : "{\"match\": {\"title\": \"foo\"}}"
} ]
},
"kibana": [
{
"base": ["all"],
"feature": {
},
"spaces": [
"default"
]
}
]
}
--------------------------------------------------
// KIBANA