Kibana APM agent keys 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 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:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_403_response'
          description: Forbidden response
        '500':
          content:
            application/json:
              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:
  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
  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_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_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_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_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_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
  examples:
    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
  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"