Create or update roles

POST /api/security/roles

Headers

  • The version of the API to use

    Value is 2023-10-31. Default value is 2023-10-31.

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json; Elastic-Api-Version=2023-10-31

Body

  • roles object Required
    Hide roles attribute Show roles attribute object
    • * object Additional properties

      Additional properties are NOT allowed.

      Hide * attributes Show * attributes object
      • A description for the role.

        Maximum length is 2048.

      • elasticsearch object Required

        Additional properties are NOT allowed.

        Hide elasticsearch attributes Show elasticsearch attributes object
        • cluster array[string]

          Cluster privileges that define the cluster level actions that users can perform.

        • indices array[object]
          Hide indices attributes Show indices attributes object
          • 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.

          • Hide field_security attribute Show field_security attribute object
            • * array[string] Additional properties

              The document fields that the role members have read access to.

          • names array[string] Required

            The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).

            At least 1 element.

          • privileges array[string] Required

            The index level privileges that the role members have for the data streams and indices.

            At least 1 element.

          • 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 array[object]
          Hide remote_cluster attributes Show remote_cluster attributes object
          • clusters array[string] Required

            A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.

            At least 1 element.

          • privileges array[string] Required

            The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.

            At least 1 element.

        • remote_indices array[object]
          Hide remote_indices attributes Show remote_indices attributes object
          • 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 array[string] Required

            A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.

            At least 1 element.

          • Hide field_security attribute Show field_security attribute object
            • * array[string] Additional properties

              The document fields that the role members have read access to.

          • names array[string] Required

            A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).

            At least 1 element.

          • privileges array[string] Required

            The index level privileges that role members have for the specified indices.

            At least 1 element.

          • 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 array[string]

          A user name that the role member can impersonate.

      • kibana array[object]
        Hide kibana attributes Show kibana attributes object
      • metadata object

        Additional properties are allowed.

Responses

  • Indicates a successful call.

POST /api/security/roles
curl \
 -X POST https://localhost:5601/api/security/roles \
 -H "Content-Type: application/json; Elastic-Api-Version=2023-10-31" \
 -H "elastic-api-version: 2023-10-31" \
 -H "kbn-xsrf: true"
Request examples
# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true

# Payload
{
  "roles": {
    "additionalProperty1": {
      "description": "string",
      "elasticsearch": {
        "cluster": [
          "string"
        ],
        "indices": [
          {
            "allow_restricted_indices": true,
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "remote_cluster": [
          {
            "clusters": [
              "string"
            ],
            "privileges": [
              "string"
            ]
          }
        ],
        "remote_indices": [
          {
            "allow_restricted_indices": true,
            "clusters": [
              "string"
            ],
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "run_as": [
          "string"
        ]
      },
      "kibana": [
        {
          "base": [],
          "feature": {
            "additionalProperty1": [
              "string"
            ],
            "additionalProperty2": [
              "string"
            ]
          },
          "spaces": [
            "*"
          ]
        }
      ],
      "metadata": {}
    },
    "additionalProperty2": {
      "description": "string",
      "elasticsearch": {
        "cluster": [
          "string"
        ],
        "indices": [
          {
            "allow_restricted_indices": true,
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "remote_cluster": [
          {
            "clusters": [
              "string"
            ],
            "privileges": [
              "string"
            ]
          }
        ],
        "remote_indices": [
          {
            "allow_restricted_indices": true,
            "clusters": [
              "string"
            ],
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "run_as": [
          "string"
        ]
      },
      "kibana": [
        {
          "base": [],
          "feature": {
            "additionalProperty1": [
              "string"
            ],
            "additionalProperty2": [
              "string"
            ]
          },
          "spaces": [
            "*"
          ]
        }
      ],
      "metadata": {}
    }
  }
}