---
type: api
title: Create or update a role
description: Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana/v8/operation/operation-put-security-role-name
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana/v8/operation/operation-put-security-role-name
products:
  - Kibana
---

# Create or update a role

- Server: `https://{kibana_url}`

## Paths

- `PUT` `/api/security/role/{name}`

#### Path parameters

- `name` (string · min length: 1 · max length: 1024) — required
  The role name.

## Description

Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.

## Authentication

- Api key: `Authorization: <value>`
  These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`
- Basic: `Authorization: Basic <credentials>`

## Query string parameters

- `createOnly` (boolean · default: false) — optional
  When true, a role is not overwritten if it already exists.

## Header parameters

- `kbn-xsrf` (string) — required
  A required header to protect against CSRF attacks

## Request body

`application/json`

- `description` (string · max length: 2048) — optional
  A description for the role.
- `elasticsearch` (object) — required
  - `cluster` (string[]) — optional
  - `indices` (object[]) — optional
    - `allow_restricted_indices` (boolean) — optional
      Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.
    - `field_security` (map string to string) — optional
    - `names` (string[] · min items: 1) — required
    - `privileges` (string[] · min items: 1) — required
    - `query` (string) — optional
      A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
  - `remote_cluster` (object[]) — optional
    - `clusters` (string[] · min items: 1) — required
    - `privileges` (string[] · min items: 1) — required
  - `remote_indices` (object[]) — optional
    - `allow_restricted_indices` (boolean) — optional
      Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.
    - `clusters` (string[] · min items: 1) — required
    - `field_security` (map string to string) — optional
    - `names` (string[] · min items: 1) — required
    - `privileges` (string[] · min items: 1) — required
    - `query` (string) — optional
      A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
  - `run_as` (string[]) — optional
- `kibana` (object[] · max items: 1000) — optional
  - `base` (union string[]) — required
    One of: `string[]`
  - `feature` (map string to string) — optional
  - `spaces` (union enum[] | string[] · default: [
  "*"
]) — optional
    Values: `*`
- `metadata` (map string to object) — optional

## Response

Indicates a successful call.

## Code examples

#### Console

```console
PUT kbn:/api/security/role/NAME
{
  "description": "Grant full access to discover and dashboard features in the default space. Grant read access in the marketing, and sales spaces.",
  "metadata": {
    "version": 1
  },
  "elasticsearch": {
    "cluster": [],
    "indices": []
  },
  "kibana": [
    {
      "base": [],
      "feature": {
        "discover": [
          "all"
        ],
        "dashboard": [
          "all"
        ]
      },
      "spaces": [
        "default"
      ]
    },
    {
      "base": [
        "read"
      ],
      "spaces": [
        "marketing",
        "sales"
      ]
    }
  ]
}
```

#### curl

```curl
curl -X PUT "${KIBANA_URL}/api/security/role/${NAME}" \
  -H "kbn-xsrf: true" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Grant full access to discover and dashboard features in the default space. Grant read access in the marketing, and sales spaces.",
    "metadata": {
      "version": 1
    },
    "elasticsearch": {
      "cluster": [],
      "indices": []
    },
    "kibana": [
      {
        "base": [],
        "feature": {
          "discover": [
            "all"
          ],
          "dashboard": [
            "all"
          ]
        },
        "spaces": [
          "default"
        ]
      },
      {
        "base": [
          "read"
        ],
        "spaces": [
          "marketing",
          "sales"
        ]
      }
    ]
  }'
```