Elastic Stack (ELK Stack) Message Signing Service 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.
  title: Kibana Message Signing Service 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: Message Signing Service
  description: Enables you to rotate message signing key pairs for secure Fleet communication.
  x-displayName: Fleet Message Signing Service
paths:
  /api/fleet/message_signing_service/rotate_key_pair:
    post:
      description: '**Spaces method and path for this operation:**


        post /s/{space_id}/api/fleet/message_signing_service/rotate_key_pair


        Refer to Spaces for more information.


        Rotate the key pair used by Fleet to sign messages sent to Elastic Agents. This operation is irreversible and requires all agents in the Fleet to be re-enrolled after rotation. You must explicitly acknowledge the risk by passing `acknowledge=true` as a query parameter.


        [Required authorization] Route required privileges: fleet-agents-all AND fleet-agent-policies-all AND fleet-settings-all.'
      operationId: post-fleet-message-signing-service-rotate-key-pair
      parameters:
      - description: A required header to protect against CSRF attacks
        in: header
        name: kbn-xsrf
        required: true
        schema:
          example: 'true'
          type: string
      - description: Set to true to confirm you understand the risks of rotating the key pair
        in: query
        name: acknowledge
        required: false
        schema:
          default: false
          type: boolean
      responses:
        '200':
          content:
            application/json:
              examples:
                rotateKeyPairSuccessExample:
                  description: The key pair was rotated. All agents must be re-enrolled to receive the new signing key.
                  value:
                    message: Key pair rotated successfully.
              schema:
                additionalProperties: false
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
          description: Key pair rotated successfully
        '400':
          content:
            application/json:
              examples:
                acknowledgeRequiredExample:
                  description: Request was rejected because the acknowledge query parameter was not set to true
                  value:
                    error: Bad Request
                    message: 'Warning: this API will cause a key pair to rotate and should not be necessary in normal operation.  If you proceed, you may need to reinstall Agents in your network. You must acknowledge the risks of rotating the key pair with acknowledge=true in the request parameters.  For more information, reach out to your administrator.'
                    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
        '500':
          content:
            application/json:
              examples:
                serviceUnavailableExample:
                  description: The message signing service is not available
                  value:
                    error: Internal Server Error
                    message: Failed to rotate key pair. Message signing service is unavailable!
                    statusCode: 500
              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: Internal Server Error
      summary: Rotate a Fleet message signing key pair
      tags:
      - Message Signing Service
      x-metaTags:
      - content: Kibana
        name: product_name
components:
  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"