Manage the roles that grant Elasticsearch and Kibana privileges.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/elk-stack:elk-stack-roles-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
contact:
name: Kibana Team
description: The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
title: Kibana Roles API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: Roles
x-displayName: Roles
description: Manage the roles that grant Elasticsearch and Kibana privileges.
externalDocs:
description: Kibana role management
url: https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles
paths:
/api/security/role:
get:
description: Retrieve all Kibana roles.
operationId: get-security-role
parameters:
- description: 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.
in: query
name: replaceDeprecatedPrivileges
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
examples:
getAllRolesResponse:
value:
- _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
getRolesResponse1:
$ref: '#/components/examples/get_roles_response1'
schema:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_response'
type: array
description: Indicates a successful call.
summary: Get all roles
tags:
- Roles
x-metaTags:
- content: Kibana
name: product_name
/api/security/role/{name}:
delete:
description: Delete a Kibana role by its name.
operationId: delete-security-role-name
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The role name.
in: path
name: name
required: true
schema:
minLength: 1
type: string
responses:
'204':
description: Indicates a successful call.
summary: Delete a role
tags:
- Roles
x-metaTags:
- content: Kibana
name: product_name
get:
description: Retrieve a Kibana role by its name.
operationId: get-security-role-name
parameters:
- description: The role name.
in: path
name: name
required: true
schema:
minLength: 1
type: string
- description: 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.
in: query
name: replaceDeprecatedPrivileges
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
examples:
getRoleResponse:
value:
_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
getRoleResponse1:
$ref: '#/components/examples/get_role_response1'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_response'
description: Indicates a successful call.
summary: Get a role
tags:
- Roles
x-metaTags:
- content: Kibana
name: product_name
put:
description: Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.
operationId: put-security-role-name
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The role name.
in: path
name: name
required: true
schema:
maxLength: 1024
minLength: 1
type: string
- description: When true, a role is not overwritten if it already exists.
in: query
name: createOnly
required: false
schema:
default: false
type: boolean
requestBody:
content:
application/json:
examples:
createOrUpdateRoleRequest:
value:
description: My custom Kibana role.
elasticsearch:
cluster:
- monitor
indices:
- names:
- logs-*
privileges:
- read
kibana:
- base:
- read
feature: {}
spaces:
- default
createRoleRequest1:
$ref: '#/components/examples/create_role_request1'
createRoleRequest2:
$ref: '#/components/examples/create_role_request2'
createRoleRequest3:
$ref: '#/components/examples/create_role_request3'
createRoleRequest4:
$ref: '#/components/examples/create_role_request4'
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_put_payload'
responses:
'204':
description: Indicates a successful call.
summary: Create or update a role
tags:
- Roles
x-metaTags:
- content: Kibana
name: product_name
/api/security/roles:
post:
description: Create or update multiple Kibana roles in a single request.
operationId: post-security-roles
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
bulkCreateOrUpdateRoles:
value:
roles:
my_kibana_role:
elasticsearch:
cluster:
- monitor
indices:
- names:
- logs-*
privileges:
- read
kibana:
- base:
- read
feature: {}
spaces:
- default
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_roles_bulk_create_or_update_payload'
responses:
'200':
content:
application/json:
examples:
bulkCreateOrUpdateRolesResponse:
value:
created:
- my_kibana_role
noop: []
updated: []
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_bulk_create_or_update_roles_response'
description: Indicates a successful call.
summary: Create or update roles
tags:
- Roles
x-metaTags:
- content: Kibana
name: product_name
components:
schemas:
Kibana_HTTP_APIs_security_bulk_create_or_update_roles_response:
additionalProperties: false
description: The response payload for the bulk create-or-update roles API.
properties:
created:
items:
description: The name of a role that was created.
type: string
type: array
errors:
additionalProperties:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_bulk_roles_error_detail'
type: object
noop:
items:
description: The name of a role that was unchanged by the request.
type: string
type: array
updated:
items:
description: The name of a role that was updated.
type: string
type: array
title: security_bulk_create_or_update_roles_response
type: object
Kibana_HTTP_APIs_security_role_put_payload:
additionalProperties: false
description: The role definition to create or update.
properties:
description:
description: A description for the role.
maxLength: 2048
type: string
elasticsearch:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_elasticsearch'
kibana:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_kibana_privilege'
type: array
metadata:
additionalProperties: {}
type: object
required:
- elasticsearch
title: security_role_put_payload
type: object
Kibana_HTTP_APIs_security_role_remote_cluster_privileges:
additionalProperties: false
description: The remote cluster privileges entry.
properties:
clusters:
items:
description: A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.
type: string
maxItems: 100
minItems: 1
type: array
privileges:
items:
description: The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.
type: string
maxItems: 100
minItems: 1
type: array
required:
- privileges
- clusters
title: security_role_remote_cluster_privileges
type: object
Kibana_HTTP_APIs_security_role_remote_indices_privileges:
additionalProperties: false
description: The remote indices privileges entry.
properties:
allow_restricted_indices:
description: 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.
type: boolean
clusters:
items:
description: A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.
type: string
maxItems: 100
minItems: 1
type: array
field_security:
additionalProperties:
items:
description: The document fields that the role members have read access to.
type: string
maxItems: 1000
type: array
type: object
names:
items:
description: A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).
type: string
maxItems: 100
minItems: 1
type: array
privileges:
items:
description: The index level privileges that role members have for the specified indices.
type: string
maxItems: 100
minItems: 1
type: array
query:
description: '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. '
type: string
required:
- clusters
- names
- privileges
title: security_role_remote_indices_privileges
type: object
Kibana_HTTP_APIs_security_role_transform_error:
additionalProperties: false
description: Diagnostic information about a role whose Kibana privileges could not be transformed.
properties:
reason:
description: The reason the role could not be fully transformed.
type: string
state:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_kibana_application'
type: array
required:
- reason
title: security_role_transform_error
type: object
Kibana_HTTP_APIs_security_role_kibana_privilege_response:
additionalProperties: false
description: A Kibana privilege entry returned for a role.
properties:
_reserved:
items:
description: A reserved Kibana privilege granted globally.
type: string
type: array
base:
items:
description: A base Kibana privilege.
type: string
type: array
feature:
additionalProperties:
items:
description: A privilege the role member has for the feature.
type: string
type: array
type: object
spaces:
items:
description: A space that the privilege applies to. The wildcard `*` indicates all spaces.
type: string
type: array
required:
- spaces
- base
- feature
title: security_role_kibana_privilege_response
type: object
Kibana_HTTP_APIs_security_bulk_roles_error_detail:
additionalProperties: false
description: Error information for a single role in a bulk create-or-update request.
properties:
reason:
description: A human readable error reason.
type: string
type:
description: The error type.
type: string
required:
- type
- reason
title: security_bulk_roles_error_detail
type: object
Kibana_HTTP_APIs_security_role_kibana_privilege:
additionalProperties: false
description: The Kibana privilege entry for the role.
properties:
base:
anyOf:
- items: {}
type: array
- type: boolean
- type: number
- type: object
- type: string
oneOf:
- items:
description: A base privilege that grants applies to all spaces.
type: string
maxItems: 50
type: array
- items:
description: A base privilege that applies to specific spaces.
type: string
maxItems: 50
type: array
feature:
additionalProperties:
items:
description: The privileges that the role member has for the feature.
type: string
maxItems: 100
type: array
type: object
spaces:
anyOf:
- items:
enum:
- '*'
type: string
maxItems: 1
minItems: 1
type: array
- items:
description: A space that the privilege applies to.
type: string
maxItems: 1000
type: array
default:
- '*'
required:
- base
title: security_role_kibana_privilege
type: object
Kibana_HTTP_APIs_security_role_elasticsearch:
additionalProperties: false
description: The Elasticsearch cluster, index, and remote cluster security privileges for the role.
properties:
cluster:
items:
description: Cluster privileges that define the cluster level actions that users can perform.
type: string
maxItems: 100
type: array
indices:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_indices_privileges'
maxItems: 1000
type: array
remote_cluster:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_remote_cluster_privileges'
maxItems: 100
type: array
remote_indices:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_remote_indices_privileges'
maxItems: 1000
type: array
run_as:
items:
description: A username that members of this role can impersonate.
type: string
maxItems: 100
type: array
title: security_role_elasticsearch
type: object
Kibana_HTTP_APIs_security_role_indices_privileges:
additionalProperties: false
description: The indices privileges entry.
properties:
allow_restricted_indices:
description: 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.
type: boolean
field_security:
additionalProperties:
items:
description: The document fields that the role members have read access to.
type: string
maxItems: 1000
type: array
type: object
names:
items:
description: The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).
type: string
maxItems: 100
minItems: 1
type: array
privileges:
items:
description: The index level privileges that the role members have for the data streams and indices.
type: string
maxItems: 100
minItems: 1
type: array
query:
description: 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.
type: string
required:
- names
- privileges
title: security_role_indices_privileges
type: object
Kibana_HTTP_APIs_security_role_response:
additionalProperties: false
description: A Kibana role definition returned by the Roles API.
properties:
_transform_error:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_transform_error'
type: array
_unrecognized_applications:
items:
description: Application names found on the role that are not recognized by Kibana.
type: string
type: array
description:
description: A description for the role.
type: string
elasticsearch:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_elasticsearch'
kibana:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_kibana_privilege_response'
type: array
metadata:
additionalProperties: {}
type: object
name:
description: The role name.
type: string
transient_metadata:
additionalProperties: {}
type: object
required:
- name
- elasticsearch
- kibana
title: security_role_response
type: object
Kibana_HTTP_APIs_security_roles_bulk_create_or_update_payload:
additionalProperties: false
description: The request body for bulk creating or updating roles.
properties:
roles:
additionalProperties:
$ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_put_payload'
type: object
required:
- roles
title: security_roles_bulk_create_or_update_payload
type: object
Kibana_HTTP_APIs_security_role_kibana_application:
additionalProperties: false
description: A raw Elasticsearch application privilege entry tied to Kibana.
properties:
application:
type: string
privileges:
items:
type: string
type: array
resources:
items:
type: string
type: array
required:
- application
- privileges
- resources
title: security_role_kibana_application
type: object
examples:
create_role_request3:
summary: Feature privileges in a space
description: Grant full access to all features in the default space.
value:
metadata:
version: 1
elasticsearch:
cluster: []
indices: []
kibana:
- base:
- all
feature: {}
spaces:
- default
get_role_response1:
summary: Get role details
value:
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: []
create_role_request2:
summary: Dashboard privileges in a space
description: Grant access to dashboard features in a Marketing space.
value:
description: Grant dashboard access in the Marketing space.
metadata:
version: 1
elasticsearch:
cluster: []
indices: []
kibana:
- base: []
feature:
dashboard:
- read
spaces:
- marketing
get_roles_response1:
summary: Get all role details
value:
- name: my_kibana_role
description: My kibana role description
metadata:
version: 1
transient_metadata:
enabled: true
elasticsearch:
indices: []
cluster: []
run_as: []
kibana:
- base:
- all
feature: {}
spaces:
- '*'
- name: my_admin_role
description: My admin role description
metadata:
version: 1
transient_metadata:
enabled: true
elasticsearch:
cluster:
- all
indices:
- names:
- index1
- index2
privileges:
- all
field_security:
grant:
- title
- body
query: '{\"match\": {\"title\": \"foo\"}}'
kibana: []
create_role_request4:
summary: Elasticsearch and Kibana feature privileges
description: Grant Elasticsearch and Kibana feature privileges.
value:
description: Grant all cluster privileges and full access to index1 and index2. Grant full access to remote_index1 and remote_index2, and the monitor_enrich cluster privilege on remote_cluster1. Grant all Kibana privileges in the default space.
metadata:
version: 1
elasticsearch:
cluster:
- all
indices:
- names:
- index1
- index2
privileges:
- all
remote_indices:
- clusters:
- remote_cluster1
names:
- remote_index1
- remote_index2
privileges:
- all
remote_cluster:
- clusters:
- remote_cluster1
privileges:
- monitor_enrich
kibana:
- base:
- all
feature: {}
spaces:
- default
create_role_request1:
summary: Feature privileges in multiple spaces
description: Grant access to various features in some spaces.
value:
description: Grant full access to discover and dashboard features in the default space. Grant read access in the marketing, and sales spaces.
metadata:
version: 1
elasticsearch:
cluster: []
indices: []
kibana:
- base: []
feature:
discover:
- all
dashboard:
- all
spaces:
- default
- base:
- read
spaces:
- marketing
- sales
securitySchemes:
apiKeyAuth:
description: 'These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`
'
in: header
name: Authorization
type: apiKey
basicAuth:
scheme: basic
type: http
x-topics:
- title: Kibana spaces
content: "Spaces enable you to organize your dashboards and other saved objects into meaningful categories.\nYou can use the default space or create your own spaces.\n\nTo run APIs in non-default spaces, you must add `s/{space_id}/` to the path.\nFor example:\n\n```bash\ncurl -X GET \"http://${KIBANA_URL}/s/marketing/api/data_views\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n```\n\nIf you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.\n\nTo learn more, check out [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces).\n"