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.

    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 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:**


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


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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_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_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_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
    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
  examples:
    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_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_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
    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_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_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
  parameters:
    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
    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
  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"