Elastic Stack (ELK Stack) Fleet enrollment API keys API

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.

    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 Fleet enrollment API keys 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: Fleet enrollment API keys
  description: 'Fleet enrollment API keys APIs enable you to manage enrollment API keys for Fleet, including creating, retrieving, and revoking API keys used for agent enrollment.

    '
  x-displayName: Fleet enrollment API keys
paths:
  /api/fleet/enrollment_api_keys:
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        List all enrollment API keys.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.'
      operationId: get-fleet-enrollment-api-keys
      parameters:
      - description: Page number
        in: query
        name: page
        required: false
        schema:
          default: 1
          type: number
      - description: Number of results per page
        in: query
        name: perPage
        required: false
        schema:
          default: 20
          type: number
      - description: A KQL query string to filter results
        in: query
        name: kuery
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                getEnrollmentApiKeysExample:
                  description: List of enrollment API keys
                  value:
                    items:
                    - active: true
                      api_key: api-key-value-1
                      api_key_id: api-key-id-1
                      created_at: '2024-01-01T00:00:00.000Z'
                      id: key-id-1
                      name: Default policy enrollment key
                      policy_id: policy-id-1
                    list:
                    - active: true
                      api_key: api-key-value-1
                      api_key_id: api-key-id-1
                      created_at: '2024-01-01T00:00:00.000Z'
                      id: key-id-1
                      name: Default policy enrollment key
                      policy_id: policy-id-1
                    page: 1
                    perPage: 20
                    total: 1
              schema:
                $ref: '#/components/schemas/Kibana_HTTP_APIs_get_enrollment_api_keys_response'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                genericErrorResponseExample:
                  description: Example of a generic error response
                  value:
                    error: Bad Request
                    message: An error message describing what went wrong
                    statusCode: 400
              schema:
                additionalProperties: false
                description: Generic Error
                type: object
                properties:
                  attributes: {}
                  error:
                    type: string
                  errorType:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
                required:
                - message
                - attributes
          description: Bad Request
      summary: Get enrollment API keys
      tags:
      - Fleet enrollment API keys
      x-metaTags:
      - content: Kibana
        name: product_name
    post:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Create an enrollment API key for a given agent policy.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.'
      operationId: post-fleet-enrollment-api-keys
      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:
              postEnrollmentApiKeyRequestExample:
                description: Create an enrollment API key for an agent policy
                value:
                  expiration: '2025-01-01T00:00:00.000Z'
                  name: My enrollment key
                  policy_id: policy-id-1
            schema:
              $ref: '#/components/schemas/Kibana_HTTP_APIs_new_enrollment_api_key'
      responses:
        '200':
          content:
            application/json:
              examples:
                postEnrollmentApiKeyExample:
                  description: The created enrollment API key
                  value:
                    action: created
                    item:
                      active: true
                      api_key: api-key-value-1
                      api_key_id: api-key-id-1
                      created_at: '2024-01-01T00:00:00.000Z'
                      id: key-id-1
                      name: My enrollment key
                      policy_id: policy-id-1
              schema:
                $ref: '#/components/schemas/Kibana_HTTP_APIs_create_enrollment_api_key_response'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                genericErrorResponseExample:
                  description: Example of a generic error response
                  value:
                    error: Bad Request
                    message: An error message describing what went wrong
                    statusCode: 400
              schema:
                additionalProperties: false
                description: Generic Error
                type: object
                properties:
                  attributes: {}
                  error:
                    type: string
                  errorType:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
                required:
                - message
                - attributes
          description: Bad Request
      summary: Create an enrollment API key
      tags:
      - Fleet enrollment API keys
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/fleet/enrollment_api_keys/_bulk_delete:
    post:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys/_bulk_delete</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Revoke or delete multiple enrollment API keys.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.'
      operationId: post-fleet-enrollment-api-keys-bulk-delete
      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:
              bulkDeleteByIdsExample:
                description: Bulk delete enrollment API keys by IDs
                value:
                  forceDelete: true
                  tokenIds:
                  - token-id-1
                  - token-id-2
              bulkDeleteByKueryExample:
                description: Bulk delete enrollment API keys by KQL query
                value:
                  forceDelete: false
                  kuery: policy_id:"policy-id-1"
            schema:
              $ref: '#/components/schemas/Kibana_HTTP_APIs_bulk_delete_enrollment_api_keys_request'
      responses:
        '200':
          content:
            application/json:
              examples:
                bulkDeleteEnrollmentApiKeysExample:
                  description: The enrollment API keys were successfully processed
                  value:
                    action: deleted
                    count: 2
                    errorCount: 0
                    successCount: 2
              schema:
                $ref: '#/components/schemas/Kibana_HTTP_APIs_bulk_delete_enrollment_api_keys_response'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                genericErrorResponseExample:
                  description: Example of a generic error response
                  value:
                    error: Bad Request
                    message: Either tokenIds or kuery must be provided
                    statusCode: 400
              schema:
                additionalProperties: false
                description: Generic Error
                type: object
                properties:
                  attributes: {}
                  error:
                    type: string
                  errorType:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
                required:
                - message
                - attributes
          description: Bad Request
      summary: Bulk revoke or delete enrollment API keys
      tags:
      - Fleet enrollment API keys
      x-state: Generally available; added in 9.5.0
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/fleet/enrollment_api_keys/{keyId}:
    delete:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb delete">delete</span>&nbsp;<span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys/{keyId}</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Revoke or delete an enrollment API key by ID. Use `forceDelete=true` to remove the document.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.'
      operationId: delete-fleet-enrollment-api-keys-keyid
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: The ID of the enrollment API key
        in: path
        name: keyId
        required: true
        schema:
          type: string
      - description: When false (default), invalidate the API key and mark the token as inactive. When true, also delete the token document.
        in: query
        name: forceDelete
        required: false
        schema:
          default: false
          type: boolean
      - description: When true, allow deletion of hidden enrollment tokens (managed/agentless policies). Defaults to false.
        in: query
        name: includeHidden
        required: false
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              examples:
                deleteEnrollmentApiKeyExample:
                  description: The enrollment API key was successfully revoked
                  value:
                    action: deleted
              schema:
                $ref: '#/components/schemas/Kibana_HTTP_APIs_delete_enrollment_api_key_response'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                genericErrorResponseExample:
                  description: Example of a generic error response
                  value:
                    error: Bad Request
                    message: An error message describing what went wrong
                    statusCode: 400
              schema:
                additionalProperties: false
                description: Generic Error
                type: object
                properties:
                  attributes: {}
                  error:
                    type: string
                  errorType:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
                required:
                - message
                - attributes
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                notFoundExample:
                  description: No enrollment API key was found with the given ID
                  value:
                    error: Not Found
                    message: EnrollmentAPIKey key-id-1 not found
                    statusCode: 404
          description: Not Found
      summary: Revoke or delete an enrollment API key
      tags:
      - Fleet enrollment API keys
      x-metaTags:
      - content: Kibana
        name: product_name
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/fleet/enrollment_api_keys/{keyId}</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Get an enrollment API key by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all OR fleet-setup.'
      operationId: get-fleet-enrollment-api-keys-keyid
      parameters:
      - description: The ID of the enrollment API key
        in: path
        name: keyId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                getEnrollmentApiKeyExample:
                  description: An enrollment API key
                  value:
                    item:
                      active: true
                      api_key: api-key-value-1
                      api_key_id: api-key-id-1
                      created_at: '2024-01-01T00:00:00.000Z'
                      id: key-id-1
                      name: Default policy enrollment key
                      policy_id: policy-id-1
              schema:
                $ref: '#/components/schemas/Kibana_HTTP_APIs_enrollment_api_key_response'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                genericErrorResponseExample:
                  description: Example of a generic error response
                  value:
                    error: Bad Request
                    message: An error message describing what went wrong
                    statusCode: 400
              schema:
                additionalProperties: false
                description: Generic Error
                type: object
                properties:
                  attributes: {}
                  error:
                    type: string
                  errorType:
                    type: string
                  message:
                    type: string
                  statusCode:
                    type: number
                required:
                - message
                - attributes
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                notFoundExample:
                  description: No enrollment API key was found with the given ID
                  value:
                    error: Not Found
                    message: EnrollmentAPIKey key-id-1 not found
                    statusCode: 404
          description: Not Found
      summary: Get an enrollment API key
      tags:
      - Fleet enrollment API keys
      x-metaTags:
      - content: Kibana
        name: product_name
components:
  schemas:
    Kibana_HTTP_APIs_new_enrollment_api_key:
      additionalProperties: false
      properties:
        expiration:
          description: The expiration time for the enrollment token, expressed as a duration (for example, 30d, 24h, 90m). By default, enrollment tokens never expire.
          maxLength: 20
          type: string
        name:
          type: string
        policy_id:
          type: string
      required:
      - policy_id
      title: new_enrollment_api_key
      type: object
    Kibana_HTTP_APIs_get_enrollment_api_keys_response:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/Kibana_HTTP_APIs_enrollment_api_key'
          maxItems: 10000
          type: array
        list:
          deprecated: true
          items:
            $ref: '#/components/schemas/Kibana_HTTP_APIs_enrollment_api_key'
          maxItems: 10000
          type: array
        page:
          type: number
        perPage:
          type: number
        total:
          type: number
      required:
      - items
      - total
      - page
      - perPage
      - list
      title: get_enrollment_api_keys_response
      type: object
    Kibana_HTTP_APIs_create_enrollment_api_key_response:
      additionalProperties: false
      properties:
        action:
          enum:
          - created
          type: string
        item:
          $ref: '#/components/schemas/Kibana_HTTP_APIs_enrollment_api_key'
      required:
      - item
      - action
      title: create_enrollment_api_key_response
      type: object
    Kibana_HTTP_APIs_enrollment_api_key:
      additionalProperties: false
      properties:
        active:
          description: When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.
          type: boolean
        api_key:
          description: The enrollment API key (token) used for enrolling Elastic Agents.
          type: string
        api_key_id:
          description: The ID of the API key in the Security API.
          type: string
        created_at:
          type: string
        expire_at:
          description: The expiration date of the enrollment token as an ISO 8601 date string. Absent when the token never expires.
          type: string
        hidden:
          type: boolean
        id:
          type: string
        name:
          description: The name of the enrollment API key.
          type: string
        policy_id:
          description: The ID of the agent policy the Elastic Agent will be enrolled in.
          type: string
      required:
      - id
      - api_key_id
      - api_key
      - active
      - created_at
      title: enrollment_api_key
      type: object
    Kibana_HTTP_APIs_delete_enrollment_api_key_response:
      additionalProperties: false
      properties:
        action:
          enum:
          - deleted
          type: string
      required:
      - action
      title: delete_enrollment_api_key_response
      type: object
    Kibana_HTTP_APIs_enrollment_api_key_response:
      additionalProperties: false
      properties:
        item:
          $ref: '#/components/schemas/Kibana_HTTP_APIs_enrollment_api_key'
      required:
      - item
      title: enrollment_api_key_response
      type: object
    Kibana_HTTP_APIs_bulk_delete_enrollment_api_keys_response:
      additionalProperties: false
      properties:
        action:
          type: string
        count:
          type: number
        errorCount:
          type: number
        successCount:
          type: number
      required:
      - action
      - count
      - successCount
      - errorCount
      title: bulk_delete_enrollment_api_keys_response
      type: object
    Kibana_HTTP_APIs_bulk_delete_enrollment_api_keys_request:
      additionalProperties: false
      properties:
        forceDelete:
          default: false
          description: When false (default), invalidate the API key and mark the token as inactive. When true, also delete the token document.
          type: boolean
        includeHidden:
          default: false
          description: When true, allow deletion of hidden enrollment tokens (managed/agentless policies). Defaults to false.
          type: boolean
        kuery:
          description: KQL query to select enrollment tokens to delete.
          type: string
        tokenIds:
          description: List of enrollment token IDs to delete.
          items:
            type: string
          maxItems: 10000
          type: array
      title: bulk_delete_enrollment_api_keys_request
      type: object
  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"