Bulk create or update roles

POST /_security/role

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.

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

Query parameters

Request body

roles map string to object required: A dictionary of role name to RoleDescriptor objects to add or update

Response

application/json

Examples

Request Console 1 / 8 languages

Run POST /_security/role to add roles called my_admin_role and my_user_role.

Console Kibana Dev Tools

POST /_security/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
          }
      }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.bulkPutRole({
  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,
      },
    },
  },
});

Python Elasticsearch Python Client

resp = client.security.bulk_put_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
            }
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/role" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": {
      "my_admin_role": {
        "cluster": [
          "all"
        ],
        "indices": [
          {
            "names": [
              "index1",
              "index2"
            ],
            "privileges": [
              "all"
            ],
            "field_security": {
              "grant": [
                "title",
                "body"
              ]
            },
            "query": "{\u0022match\u0022: {\u0022title\u0022: \u0022foo\u0022}}"
          }
        ],
        "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": "{\u0022match\u0022: {\u0022title\u0022: \u0022foo\u0022}}"
          }
        ],
        "applications": [
          {
            "application": "myapp",
            "privileges": [
              "admin",
              "read"
            ],
            "resources": [
              "*"
            ]
          }
        ],
        "run_as": [
          "other_user"
        ],
        "metadata": {
          "version": 1
        }
      }
    }
  }'

Java Elasticsearch Java Client

client.security().bulkPutRole(b -> b
    .roles(Map.of("my_admin_role", RoleDescriptor.roleDescriptorOf(r -> r
            .cluster("all")
            .indices(i -> i
                .fieldSecurity(f -> f
                    .grant(List.of("title","body"))
                )
                .names(List.of("index1","index2"))
                .privileges("all")
                .query(q -> q
                    .match(m -> m
                        .field("title")
                        .query(FieldValue.of("foo"))
                    )
                )
            )
            .applications(a -> a
                .application("myapp")
                .privileges(List.of("admin","read"))
                .resources("*")
            )
            .metadata("version", JsonData.fromJson("1"))
            .runAs("other_user")
        ),"my_user_role", RoleDescriptor.roleDescriptorOf(ro -> ro
            .cluster("all")
            .indices(i -> i
                .fieldSecurity(f -> f
                    .grant(List.of("title","body"))
                )
                .names("index1")
                .privileges("read")
                .query(q -> q
                    .match(m -> m
                        .field("title")
                        .query(FieldValue.of("foo"))
                    )
                )
            )
            .applications(a -> a
                .application("myapp")
                .privileges(List.of("admin","read"))
                .resources("*")
            )
            .metadata("version", JsonData.fromJson("1"))
            .runAs("other_user")
        )))
);

C# Elasticsearch .NET Client

var response = await client.Security
    .BulkPutRoleAsync(d1 => d1
        .Roles(d2 => d2
            .Add("my_admin_role", d3 => d3
                .Applications(d4 => d4
                    .Application("myapp")
                    .Privileges("admin", "read")
                    .Resources("*")
                )
                .Cluster(ClusterPrivilege.All)
                .Indices(d4 => d4
                    .FieldSecurity(d5 => d5
                        .Grant(x => x.Title, x => x.Body)
                    )
                    .Names(["index1", "index2"])
                    .Privileges(IndexPrivilege.All)
                    .Query("{\"match\": {\"title\": \"foo\"}}")
                )
                .Metadata(new Dictionary<string, object>()
                {
                    { "version", 1 }
                })
                .RunAs("other_user")
            )
            .Add("my_user_role", d3 => d3
                .Applications(d4 => d4
                    .Application("myapp")
                    .Privileges("admin", "read")
                    .Resources("*")
                )
                .Cluster(ClusterPrivilege.All)
                .Indices(d4 => d4
                    .FieldSecurity(d5 => d5
                        .Grant(x => x.Title, x => x.Body)
                    )
                    .Names(["index1"])
                    .Privileges(IndexPrivilege.Read)
                    .Query("{\"match\": {\"title\": \"foo\"}}")
                )
                .Metadata(new Dictionary<string, object>()
                {
                    { "version", 1 }
                })
                .RunAs("other_user")
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->bulkPutRole([
    "body" => [
        "roles" => [
            "my_admin_role" => [
                "cluster" => array(
                    "all",
                ),
                "indices" => array(
                    [
                        "names" => array(
                            "index1",
                            "index2",
                        ),
                        "privileges" => array(
                            "all",
                        ),
                        "field_security" => [
                            "grant" => array(
                                "title",
                                "body",
                            ),
                        ],
                        "query" => "{\"match\": {\"title\": \"foo\"}}",
                    ],
                ),
                "applications" => array(
                    [
                        "application" => "myapp",
                        "privileges" => array(
                            "admin",
                            "read",
                        ),
                        "resources" => array(
                            "*",
                        ),
                    ],
                ),
                "run_as" => array(
                    "other_user",
                ),
                "metadata" => [
                    "version" => 1,
                ],
            ],
            "my_user_role" => [
                "cluster" => array(
                    "all",
                ),
                "indices" => array(
                    [
                        "names" => array(
                            "index1",
                        ),
                        "privileges" => array(
                            "read",
                        ),
                        "field_security" => [
                            "grant" => array(
                                "title",
                                "body",
                            ),
                        ],
                        "query" => "{\"match\": {\"title\": \"foo\"}}",
                    ],
                ),
                "applications" => array(
                    [
                        "application" => "myapp",
                        "privileges" => array(
                            "admin",
                            "read",
                        ),
                        "resources" => array(
                            "*",
                        ),
                    ],
                ),
                "run_as" => array(
                    "other_user",
                ),
                "metadata" => [
                    "version" => 1,
                ],
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.bulk_put_role(
  body: {
    "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
        }
      }
    }
  }
)

Response

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"
    ]
}

Request Console 1 / 2 languages

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.

Console Kibana Dev Tools

POST /_security/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
          }
      }
  }
}

Generated from the API spec

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/role" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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
            }
        }
    }
  }'

Generated from the API spec

Response

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"
    ]
}

Request Console 1 / 2 languages

Run POST /_security/role/only_remote_access_role to configure a role with remote indices and remote cluster privileges for a remote cluster.

Console Kibana Dev Tools

POST /_security/role/only_remote_access_role
{
  "remote_indices": [
    {
      "clusters": ["my_remote"], 
      "names": ["logs*"], 
      "privileges": ["read", "read_cross_cluster", "view_index_metadata"] 
    }
  ],
  "remote_cluster": [
    {
      "clusters": ["my_remote"], 
      "privileges": ["monitor_stats"]  
    }
  ]
}

Generated from the API spec

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/role/only_remote_access_role" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "remote_indices": [
      {
        "clusters": ["my_remote"], 
        "names": ["logs*"], 
        "privileges": ["read", "read_cross_cluster", "view_index_metadata"] 
      }
    ],
    "remote_cluster": [
      {
        "clusters": ["my_remote"], 
        "privileges": ["monitor_stats"]  
      }
    ]
  }'

Generated from the API spec

Response

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"
    ]
}

Required authorization

Authentication

Query parameters

Request body { }

Response

Request body