Bulk create or update roles Added in 8.15.0

POST /_security/role
Api key auth Basic auth Bearer auth

The role management APIs are generally the preferred way to manage roles, rather than using file-based role management. The bulk create or update roles API cannot update roles that are defined in roles files.

Query parameters

  • refresh string

    If true (the default) then refresh the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false then do nothing with refreshes.

    Values are true, false, or wait_for.

application/json

Body Required

  • roles object Required

    A dictionary of role name to RoleDescriptor objects to add or update

    Hide roles attribute Show roles attribute object
    • * object Additional properties
      Hide * attributes Show * attributes object
      • cluster array[string]

        A list of cluster privileges. These privileges define the cluster level actions that API keys are able to execute.

      • indices array[object]

        A list of indices permissions entries.

        Hide indices attributes Show indices attributes object
      • remote_indices array[object]

        A list of indices permissions for remote clusters.

        Hide remote_indices attributes Show remote_indices attributes object
      • remote_cluster array[object]

        A list of cluster permissions for remote clusters. NOTE: This is limited a subset of the cluster permissions.

        Hide remote_cluster attributes Show remote_cluster attributes object
        • clusters string | array[string] Required
        • privileges array[string] Required

          The cluster level privileges that owners of the role have on the remote cluster.

          Values are monitor_enrich or monitor_stats.

      • global array[object] | object

        An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.

        One of:
        array-1 array[object] _types:GlobalPrivilege object
        Hide attribute Show attribute object
        • application object Required
          Hide application attribute Show application attribute object
      • applications array[object]

        A list of application privilege entries

        Hide applications attributes Show applications attributes object
        • application string Required

          The name of the application to which this entry applies.

        • privileges array[string] Required

          A list of strings, where each element is the name of an application privilege or action.

        • resources array[string] Required

          A list resources to which the privileges are applied.

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

        A list of users that the API keys can impersonate. NOTE: In Elastic Cloud Serverless, the run-as feature is disabled. For API compatibility, you can still specify an empty run_as field, but a non-empty list will be rejected.

      • description string

        Optional description of the role descriptor

      • restriction object
        Hide restriction attribute Show restriction attribute object
        • workflows array[string] Required

          A list of workflows to which the API key is restricted. NOTE: In order to use a role restriction, an API key must be created with a single role descriptor.

      • transient_metadata object
        Hide transient_metadata attribute Show transient_metadata attribute object
        • * object Additional properties

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • created array[string]

      Array of created roles

    • updated array[string]

      Array of updated roles

    • noop array[string]

      Array of role names without any changes

    • errors object
      Hide errors attributes Show errors attributes object
      • count number Required

        The number of errors

      • details object Required

        Details about the errors, keyed by role name

        Hide details attribute Show details attribute object
        • * object
          Hide * attributes Show * attributes object
POST /_security/role 
curl \
 --request POST 'http://api.example.com/_security/role' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"roles\": {\n      \"my_admin_role\": {\n          \"cluster\": [\n              \"all\"\n          ],\n          \"indices\": [\n              {\n                  \"names\": [\n                      \"index1\",\n                      \"index2\"\n                  ],\n                  \"privileges\": [\n                      \"all\"\n                  ],\n                  \"field_security\": {\n                      \"grant\": [\n                          \"title\",\n                          \"body\"\n                      ]\n                  },\n                  \"query\": \"{\\\"match\\\": {\\\"title\\\": \\\"foo\\\"}}\"\n              }\n          ],\n          \"applications\": [\n              {\n                  \"application\": \"myapp\",\n                  \"privileges\": [\n                      \"admin\",\n                      \"read\"\n                  ],\n                  \"resources\": [\n                      \"*\"\n                  ]\n              }\n          ],\n          \"run_as\": [\n              \"other_user\"\n          ],\n          \"metadata\": {\n              \"version\": 1\n          }\n      },\n      \"my_user_role\": {\n          \"cluster\": [\n              \"all\"\n          ],\n          \"indices\": [\n              {\n                  \"names\": [\n                      \"index1\"\n                  ],\n                  \"privileges\": [\n                      \"read\"\n                  ],\n                  \"field_security\": {\n                      \"grant\": [\n                          \"title\",\n                          \"body\"\n                      ]\n                  },\n                  \"query\": \"{\\\"match\\\": {\\\"title\\\": \\\"foo\\\"}}\"\n              }\n          ],\n          \"applications\": [\n              {\n                  \"application\": \"myapp\",\n                  \"privileges\": [\n                      \"admin\",\n                      \"read\"\n                  ],\n                  \"resources\": [\n                      \"*\"\n                  ]\n              }\n          ],\n          \"run_as\": [\n              \"other_user\"\n          ],\n          \"metadata\": {\n              \"version\": 1\n          }\n      }\n  }\n}"'
Request examples
Run `POST /_security/role` to add roles called `my_admin_role` and `my_user_role`. 
{
  "roles": {
      "my_admin_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1",
                      "index2"
                  ],
                  "privileges": [
                      "all"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      },
      "my_user_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1"
                  ],
                  "privileges": [
                      "read"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      }
  }
}
Because errors are handled individually for each role create or update, the API allows partial success. For example, `POST /_security/role` would throw an error for `my_admin_role` because the privilege `bad_cluster_privilege` doesn't exist, but would be successful for the `my_user_role`. 
{
  "roles": {
      "my_admin_role": {
          "cluster": [
              "bad_cluster_privilege"
          ],
          "indices": [
              {
                  "names": [
                      "index1",
                      "index2"
                  ],
                  "privileges": ["all"],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      },
      "my_user_role": {
          "cluster": [
              "all"
          ],
          "indices": [
              {
                  "names": [
                      "index1"
                  ],
                  "privileges": [
                      "read"
                  ],
                  "field_security": {
                      "grant": [
                          "title",
                          "body"
                      ]
                  },
                  "query": "{\"match\": {\"title\": \"foo\"}}"
              }
          ],
          "applications": [
              {
                  "application": "myapp",
                  "privileges": [
                      "admin",
                      "read"
                  ],
                  "resources": [
                      "*"
                  ]
              }
          ],
          "run_as": [
              "other_user"
          ],
          "metadata": {
              "version": 1
          }
      }
  }
}
Run `POST /_security/role/only_remote_access_role` to configure a role with remote indices and remote cluster privileges for a remote cluster. 
{
  "remote_indices": [
    {
      "clusters": ["my_remote"], 
      "names": ["logs*"], 
      "privileges": ["read", "read_cross_cluster", "view_index_metadata"] 
    }
  ],
  "remote_cluster": [
    {
      "clusters": ["my_remote"], 
      "privileges": ["monitor_stats"]  
    }
  ]
}
Response examples (200)
A successful response from `POST /_security/role/my_admin_role` returns a JSON structure that shows whether the role has been created, updated, or had no changes made. 
{
    "created": [ 
        "my_admin_role", 
        "my_user_role"
    ]
}
A partially successful response from `POST /_security/role`. Errors are handled individually for each role create or update, thus the API allows partial success. In this example, the creation of the `my_user_role` role succeeds and the `my_admin_role` role fails. 
{
  "created": [
      "my_user_role" 
  ],
  "errors": { 
      "count": 1, 
      "details": {
          "my_admin_role": { 
              "type": "action_request_validation_exception",
              "reason": "Validation Failed: 1: unknown cluster privilege [bad_cluster_privilege]. a privilege must be either one of the predefined cluster privilege names [manage_own_api_key,manage_data_stream_global_retention,monitor_data_stream_global_retention,none,cancel_task,cross_cluster_replication,cross_cluster_search,delegate_pki,grant_api_key,manage_autoscaling,manage_index_templates,manage_logstash_pipelines,manage_oidc,manage_saml,manage_search_application,manage_search_query_rules,manage_search_synonyms,manage_service_account,manage_token,manage_user_profile,monitor_connector,monitor_enrich,monitor_inference,monitor_ml,monitor_rollup,monitor_snapshot,monitor_stats,monitor_text_structure,monitor_watcher,post_behavioral_analytics_event,read_ccr,read_connector_secrets,read_fleet_secrets,read_ilm,read_pipeline,read_security,read_slm,transport_client,write_connector_secrets,write_fleet_secrets,create_snapshot,manage_behavioral_analytics,manage_ccr,manage_connector,manage_enrich,manage_ilm,manage_inference,manage_ml,manage_rollup,manage_slm,manage_watcher,monitor_data_frame_transforms,monitor_transform,manage_api_key,manage_ingest_pipelines,manage_pipeline,manage_data_frame_transforms,manage_transform,manage_security,monitor,manage,all] or a pattern over one of the available cluster actions;"
          }
      }
  }
}