Kibana roles API

openapi: 3.0.3
info:
  contact:
    name: Kibana Team
  description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.

    The API calls are stateless.

    Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the

    request.

    API requests return JSON output, which is a format that is machine-readable and works well for automation.


    To interact with Kibana APIs, use the following operations:


    - GET: Fetches the information.

    - PATCH: Applies partial modifications to the existing information.

    - POST: Adds new information.

    - PUT: Updates the existing information.

    - DELETE: Removes the information.


    You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.

    For example:


    ```

    GET kbn:/api/data_views

    ```


    For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).


    NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.


    ## Documentation source and versions


    This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.

    It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).


    This documentation contains work-in-progress information for future Elastic Stack releases.

    '
  title: Kibana APIs Actions 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:
      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':
          description: Indicates a successful call.
          content:
            application/json:
              examples:
                getRolesResponse1:
                  $ref: '#/components/examples/get_roles_response1'
      summary: Get all roles
      tags:
      - roles
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/security/role/{name}:
    delete:
      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:
      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':
          description: Indicates a successful call.
          content:
            application/json:
              examples:
                getRoleResponse1:
                  $ref: '#/components/examples/get_role_response1'
      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:
            schema:
              $ref: '#/components/schemas/Kibana_HTTP_APIs_security_role_put_payload'
            examples:
              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'
      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:
      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:
            schema:
              $ref: '#/components/schemas/Kibana_HTTP_APIs_security_roles_bulk_create_or_update_payload'
      responses:
        '200':
          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_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
          nullable: true
          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_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:
            nullable: true
          type: object
      required:
      - elasticsearch
      title: security_role_put_payload
      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_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_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_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
  examples:
    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_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
    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_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
  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"