---
type: api
title: Get a role
description: Retrieve a Kibana role by its name.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-get-security-role-name
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-get-security-role-name
products:
  - Kibana
---

# Get a role

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

## Paths

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

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#basicauth)

#### Path Parameters

- `name` (string · min: 1)
  The role name.

## Description

Retrieve a Kibana role by its name.

## Query String Parameters

- `replaceDeprecatedPrivileges` (boolean)
  If `true` and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.

## Response

Indicates a successful call.

`application/json`

- `_transform_error` ([] object)
  - `reason` (string)
    The reason the role could not be fully transformed.
  - `state` ([] object)
    - `application` (string)
    - `privileges` ([] string)
    - `resources` ([] string)
- `_unrecognized_applications` ([] string)
- `description` (string)
  A description for the role.
- `elasticsearch` ({})
  The Elasticsearch cluster, index, and remote cluster security privileges for the role.
  - `cluster` ([] string · max: 100)
  - `global` ({})
    Global privileges for the role.
    - `application` (object)
      - `manage` (object)
        - `applications` ([] string · max: 1000)
    - `data_source` ([] object · max: 1000)
      - `names` ([] string · min: 1 · max: 100)
      - `privileges` ([] enum  · min: 1 · max: 5)
        The data source privileges that role members have for the specified data sources.
        Values: `create`, `read_metadata`, `delete`, `read`, `manage`
    - `profile` (object)
      - `write` (object)
        - `applications` ([] string · max: 1000)
    - `role` (object)
      Global role privileges.
  - `indices` ([] object · max: 1000)
    - `allow_restricted_indices` (boolean)
      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)
    - `names` ([] string · min: 1 · max: 100)
    - `privileges` ([] string · min: 1 · max: 100)
    - `query` (string)
      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 · max: 100)
    - `clusters` ([] string · min: 1 · max: 100)
    - `privileges` ([] string · min: 1 · max: 100)
  - `remote_indices` ([] object · max: 1000)
    - `allow_restricted_indices` (boolean)
      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: 1 · max: 100)
    - `field_security` (map string to string)
    - `names` ([] string · min: 1 · max: 100)
    - `privileges` ([] string · min: 1 · max: 100)
    - `query` (string)
      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 · max: 100)
- `kibana` ([] object)
  - `_reserved` ([] string)
  - `base` ([] string)
  - `feature` (map string to string)
  - `spaces` ([] string)
- `metadata` (map string to object)
- `name` (string)
  The role name.
- `transient_metadata` (map string to object)
## Code Examples

#### Console

```console
GET /api/security/role/{name}
```

#### curl

```curl
curl -X GET "https://{kibana_url}/api/security/role/{name}"
```

## Response Examples

#### Get role

```json
{
  "_unrecognized_applications": [],
  "description": "My custom Kibana role.",
  "elasticsearch": {
    "cluster": [
      "monitor"
    ],
    "indices": [
      {
        "names": [
          "logs-*"
        ],
        "privileges": [
          "read"
        ]
      }
    ],
    "run_as": []
  },
  "kibana": [
    {
      "base": [
        "read"
      ],
      "feature": {},
      "spaces": [
        "default"
      ]
    }
  ],
  "metadata": {},
  "name": "my_kibana_role",
  "transient_metadata": {
    "enabled": true
  }
}
```

#### Get role details

```json
{
  "name": "my_kibana_role",
  "description": "Grants all cluster privileges and full access to index1 and index2. Grants full access to remote_index1 and remote_index2, and the monitor_enrich cluster privilege on remote_cluster1. Grants all Kibana privileges in the default space.",
  "metadata": {
    "version": 1
  },
  "transient_metadata": {
    "enabled": true
  },
  "elasticsearch": {
    "cluster": [
      "all"
    ],
    "remote_cluster": [
      {
        "privileges": [
          "monitor_enrich"
        ],
        "clusters": [
          "remote_cluster1"
        ]
      }
    ],
    "indices": [
      {
        "names": [
          "index1",
          "index2"
        ],
        "privileges": [
          "all"
        ],
        "allow_restricted_indices": false
      }
    ],
    "remote_indices": [
      {
        "names": [
          "remote_index1",
          "remote_index2"
        ],
        "privileges": [
          "all"
        ],
        "allow_restricted_indices": false,
        "clusters": [
          "remote_cluster1"
        ]
      }
    ],
    "run_as": []
  },
  "kibana": [
    {
      "base": [
        "all"
      ],
      "feature": {},
      "spaces": [
        "default"
      ]
    }
  ],
  "_transform_error": [],
  "_unrecognized_applications": []
}
```