Elastic Stack (ELK Stack) APM agent 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.
  title: Kibana APM agent 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:
- description: Configure APM agent keys to authorize requests from APM agents to the APM Server.
  name: APM agent keys
paths:
  /api/apm/agent_keys:
    post:
      description: '**Spaces method and path for this operation:**


        post /s/{space_id}/api/apm/agent_keys


        Refer to Spaces for more information.


        Create a new agent key for APM.

        The user creating an APM agent API key must have at least the `manage_own_api_key` cluster privilege and the APM application-level privileges that it wishes to grant.

        After it is created, you can copy the API key (Base64 encoded) and use it to to authorize requests from APM agents to the APM Server.'
      operationId: createAgentKey
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - $ref: '#/components/parameters/APM_UI_kbn_xsrf'
      requestBody:
        content:
          application/json:
            examples:
              createAgentKeyRequest1:
                $ref: '#/components/examples/APM_UI_agent_keys_object_post_request1'
            schema:
              $ref: '#/components/schemas/APM_UI_agent_keys_object'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                createAgentKeyResponse1:
                  $ref: '#/components/examples/APM_UI_agent_keys_object_post_200_response1'
              schema:
                $ref: '#/components/schemas/APM_UI_agent_keys_response'
          description: Agent key created successfully
        '400':
          content:
            application/json:
              examples:
                badRequestResponse:
                  $ref: '#/components/examples/APM_UI_error_400_response'
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              examples:
                unauthorizedResponse:
                  $ref: '#/components/examples/APM_UI_error_401_response'
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '403':
          content:
            application/json:
              examples:
                forbiddenResponse:
                  $ref: '#/components/examples/APM_UI_error_403_response'
              schema:
                $ref: '#/components/schemas/APM_UI_403_response'
          description: Forbidden response
        '500':
          content:
            application/json:
              examples:
                internalServerErrorResponse:
                  $ref: '#/components/examples/APM_UI_error_500_response'
              schema:
                $ref: '#/components/schemas/APM_UI_500_response'
          description: Internal Server Error response
      summary: Create an APM agent key
      tags:
      - APM agent keys
      x-metaTags:
      - content: Kibana
        name: product_name
components:
  schemas:
    APM_UI_403_response:
      type: object
      properties:
        error:
          description: Error type
          example: Forbidden
          type: string
        message:
          description: Error message
          type: string
        statusCode:
          description: Error status code
          example: 403
          type: number
    APM_UI_agent_keys_object:
      type: object
      properties:
        name:
          description: The name of the APM agent key.
          type: string
        privileges:
          description: 'The APM agent key privileges. It can take one or more of the following values:

            * `event:write`, which is required for ingesting APM agent events. * `config_agent:read`, which is required for APM agents to read agent configuration remotely.

            '
          items:
            enum:
            - event:write
            - config_agent:read
            type: string
          type: array
      required:
      - name
      - privileges
    APM_UI_agent_keys_response:
      type: object
      properties:
        agentKey:
          description: Agent key
          type: object
          properties:
            api_key:
              type: string
            encoded:
              type: string
            expiration:
              format: int64
              type: integer
            id:
              type: string
            name:
              type: string
          required:
          - id
          - name
          - api_key
          - encoded
    APM_UI_401_response:
      type: object
      properties:
        error:
          description: Error type
          example: Unauthorized
          type: string
        message:
          description: Error message
          type: string
        statusCode:
          description: Error status code
          example: 401
          type: number
    APM_UI_400_response:
      type: object
      properties:
        error:
          description: Error type
          example: Not Found
          type: string
        message:
          description: Error message
          example: Not Found
          type: string
        statusCode:
          description: Error status code
          example: 400
          type: number
    APM_UI_500_response:
      type: object
      properties:
        error:
          description: Error type
          example: Internal Server Error
          type: string
        message:
          description: Error message
          type: string
        statusCode:
          description: Error status code
          example: 500
          type: number
  parameters:
    APM_UI_elastic_api_version:
      description: The version of the API to use
      in: header
      name: elastic-api-version
      required: true
      schema:
        default: '2023-10-31'
        enum:
        - '2023-10-31'
        type: string
    APM_UI_kbn_xsrf:
      description: A required header to protect against CSRF attacks
      in: header
      name: kbn-xsrf
      required: true
      schema:
        example: 'true'
        type: string
  examples:
    APM_UI_agent_keys_object_post_request1:
      description: Run `POST /api/apm/agent_keys` to create an APM agent API key with the specified privileges.
      value:
        name: apm-key
        privileges:
        - event:write
        - config_agent:read
    APM_UI_error_400_response:
      description: An example of a 400 Bad Request response, returned when the request payload or query parameters fail validation.
      value:
        error: Bad Request
        message: '[request body]: expected value of type [string] but got [undefined]'
        statusCode: 400
    APM_UI_agent_keys_object_post_200_response1:
      description: An example of a successful response from `POST /api/apm/agent_keys`, which creates an APM agent API key.
      value:
        agentKey:
          api_key: PjGloCGOTzaZr8ilUPvkjA
          encoded: M0RDTG1uMEIzWk1oTFVhN1dCRzk6UGpHbG9DR09UemFacjhpbFVQdmtqQQ==
          id: 3DCLmn0B3ZMhLUa7WBG9
          name: apm-key
    APM_UI_error_403_response:
      description: An example of a 403 Forbidden response, returned when the authenticated user lacks the required APM and User Experience privileges.
      value:
        error: Forbidden
        message: Insufficient privileges to perform this action. The APM and User Experience feature requires `all` privileges.
        statusCode: 403
    APM_UI_error_401_response:
      description: An example of a 401 Unauthorized response, returned when the request is missing valid authentication credentials.
      value:
        error: Unauthorized
        message: '[security_exception]: missing authentication credentials for REST request'
        statusCode: 401
    APM_UI_error_500_response:
      description: An example of a 500 Internal Server Error response, returned when an unexpected error occurs while processing the request.
      value:
        error: Internal Server Error
        message: An internal server error occurred. Check the Kibana server logs for details.
        statusCode: 500
  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"