kibana/docs/api/role-management/put.asciidoc

[[role-management-api-put]]
=== Create or update role API
++++
<titleabbrev>Create or update role</titleabbrev>
++++

experimental[] Create a new {kib} role, or update the attributes of an existing role. {kib} roles are stored in the
{es} native realm.

[[role-management-api-put-request]]
==== Request

`PUT <kibana host>:<port>/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="child_attributes"]
[[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 <<kibana-privileges, Kibana privileges>> for the role.
+
.Properties of `kibana`
[%collapsible%open]
=====
`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 <<features-api-get, features API>>.

`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,sh]
--------------------------------------------------
$ curl -X 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,sh]
--------------------------------------------------
$ curl -X 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,sh]
--------------------------------------------------
$ curl -X 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,sh]
--------------------------------------------------
$ curl -X 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 {es}:

[source,sh]
--------------------------------------------------
$ curl -X 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