Query parameters
If
true(the default) then refresh the affected shards to make this operation visible to search, ifwait_forthen wait for a refresh to make this operation visible to search, iffalsethen do nothing with refreshes.Values are
true,false, orwait_for.
POST /_security/role
Console
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
}
}
}
}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
Bulk role success
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
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;"
}
}
}
}