openapi: 3.1.0
info:
  title: Audit Logs API - Fetch Audit Logs
  description: APIs to retrieve audit logs of one or more services.
  license:
    name: HPE License
    url: https://www.hpe.com/us/en/software/licensing.html
  version: v2beta1
servers:
  - url: https://global.api.greenlake.hpe.com
security:
  - Bearer: []
tags:
  - name: Fetch Audit Logs
    description: Retrieves audit logs of one or more services.
paths:
  /audit-log/v2beta1/logs:
    get:
      summary: Retrieves audit logs of one or more services.
      description: >
        The audit logs can be filtered using a variety of parameters. Queries
        should be separated by `and` and can utilize `eq`, `contains`, and `in`
        operators to construct the final query. Each query should follow the
        format:
         * key eq 'value' for equality operation.
         * contains(key, 'value') for contains operation.
         * key in ('value1', 'value2') for in operation.

        | **Filter Parameter** | **Supported Operators** |
        **Type**                | **Example** |

        |-----------------------|-------------------------|--------------------------|--------------|

        | **createdAt**         | `lt`, `ge`              | RFC timestamp
        (string)   | `createdAt ge '2024-02-16T07:54:55.0Z'` |

        | **category**          | `eq`, `in`              |
        string                   | `category eq 'User Management'`<br>`category
        in ('Device Management', 'User Activity')` |

        | **description**       | `eq`, `contains`        |
        string                   | `contains(description, 'Logged
        in')`<br>`description eq 'User test@test.com logged in via ping mode.'`
        |

        | **ipAddress**         | `eq`, `contains`        | IP
        string                | `ipAddress eq
        '192.168.12.12'`<br>`contains(ipAddress, '192.168')` |

        | **username**          | `eq`, `contains`        | email
        (string)           | `username eq
        'test@test.com'`<br>`contains(username, '@gmail.com')` |

        | **workspace/name**    | `eq`, `contains`        |
        string                   | `workspace/name eq 'Example
        workspace'`<br>`contains(workspace/name, 'Example')` |

        | **workspace/type**    | `eq`                    |
        string                   | `workspace/type eq
        'TENANT'`<br>`workspace/type eq 'MSP'` |

        | **serviceOffer/id**   | `eq`, `in`              | UUID
        (string)            | `serviceOffer/id eq
        '902fa943-dcfc-432c-a92c-3a3a454923d9'`<br>`serviceOffer/id in
        ('902fa943-dcfc-432c-a92c-3a3a454923d9',
        '00000000-0000-0000-0000-000000000000')` |

        | **region**            | `eq`                    | region code
        (string)     | `region eq 'us-west'` |

        | **hasDetails**        | `eq`                    |
        boolean                  | `hasDetails eq 'true'` |

         **Note**: Maximum five serviceOffer/id can be passed in the filter. If no serviceOffer/id is passed, only platform audit logs will be fetched.
         **Note**: Maximum five serviceOffer/id can be passed in the filter. If no serviceOffer/id is passed, only HPE GreenLake Platform Audit logs will be fetched.

         The API supports pagination and sorting options to efficiently retrieve large datasets

         Rate limits:
         - 100 requests per minute per user.
         - 300 requests per minute overall.
      tags:
        - Fetch Audit Logs
      operationId: getAuditLogs
      parameters:
        - name: filter
          in: query
          schema:
            type: string
          examples:
            Get only platform audit logs:
              description: Get HPE GreenLake platform audit logs
              value: serviceOffer/id eq '00000000-0000-0000-0000-000000000000'
            Get multiple service offer audit logs:
              description: Get HPE GreenLake platform and Compute cloud console logs
              value: >-
                serviceOffer/id in ('00000000-0000-0000-0000-000000000000',
                'd46569ae-0516-4dd2-81ce-b6d645842acc') and region eq 'us-west'
            Filter based on category and time range:
              description: >-
                Get audit logs for API Gateway category within a specific time
                range
              value: >-
                category eq 'API Gateway' and createdAt ge
                '2025-01-16T07:54:55.0Z' and createdAt lt
                '2025-02-16T07:54:55.0Z'
            Filter based on username:
              description: Get audit logs for a specific user
              value: username eq 'test@test.com'
          required: false
        - name: select
          required: false
          in: query
          description: >
            Use the `select` query parameter to restrict the number of
            properties included in the audit log response.

            Specify as comma-separated values. The supported select parameters
            are:
             * serviceOffer
             * createdAt
             * category
             * hasDetails
             * workspace
             * description
             * username
             * ipAddress
             * additionalInfo
          schema:
            type: string
          examples:
            Get all attributes:
              description: Get audit logs with all attributes
              value: >-
                serviceOffer, createdAt, category, hasDetails, workspace,
                description, username, ipAddress, additionalInfo
            Get selected attributes:
              description: Get audit logs with selected attributes
              value: createdAt, username, category
        - name: limit
          in: query
          description: How many items to return at one time (max 2000)
          required: false
          schema:
            type: integer
            maximum: 2000
            default: 50
        - name: offset
          in: query
          description: Specifies the zero-based resource offset to start the response from.
          required: false
          schema:
            type: integer
            default: 0
        - name: sort
          in: query
          description: >
            Sort the results based on the specified field. The default sort
            order is descending. Each sort expression is a property name
            optionally followed by a direction indicator asc (ascending) or desc
            (descending).
          required: false
          schema:
            type: string
          examples:
            Sort by createdAt in descending order:
              value: createdAt
            Sort by category in ascending order:
              value: category asc
      responses:
        '200':
          description: Audit logs fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogQueryResponse'
              examples:
                AuditLogQueryResponseExample:
                  $ref: '#/components/examples/AuditLogQueryResponseExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequestDetails'
              examples:
                ErrorBadRequestExample:
                  $ref: '#/components/examples/ErrorBadRequestExample'
                UnsupportedFilterParameterError:
                  $ref: '#/components/examples/UnsupportedFilterParameterError'
                InvalidRegionValueError:
                  $ref: '#/components/examples/InvalidRegionValueError'
                InvalidFilterOperatorError:
                  $ref: '#/components/examples/InvalidFilterOperatorError'
                InvalidDateFormatError:
                  $ref: '#/components/examples/InvalidDateFormatError'
                InvalidLimitValueError:
                  $ref: '#/components/examples/InvalidLimitValueError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                ErrorUnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                ErrorForbiddenExample:
                  $ref: '#/components/examples/ErrorForbiddenExample'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseError'
              examples:
                TooManyRequestsError:
                  $ref: '#/components/examples/TooManyRequestsError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRetryDetails'
              examples:
                Internal-Server-Error:
                  $ref: '#/components/examples/InternalServerError'
  /audit-log/v2beta1/logs/{id}:
    get:
      summary: Get a specific audit log.
      tags:
        - Fetch Audit Logs
      operationId: getAuditLog
      parameters:
        - name: id
          in: path
          required: true
          description: Provide the ID of the audit log record to fetch the audit log.
          schema:
            type: string
      responses:
        '200':
          description: Audit log details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogItem'
              examples:
                AuditLogExample:
                  $ref: '#/components/examples/AuditLogItemExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                ErrorUnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                ErrorForbiddenExample:
                  $ref: '#/components/examples/ErrorForbiddenExample'
        '404':
          description: Record Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                AuditLogNotFoundExample:
                  $ref: '#/components/examples/AuditLogNotFoundExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRetryDetails'
              examples:
                Internal-Server-Error:
                  $ref: '#/components/examples/InternalServerError'
  /audit-log/v2beta1/logs/{id}/details:
    get:
      summary: Get a specific audit log details.
      tags:
        - Fetch Audit Logs
      operationId: getAuditLogDetails
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            Provide the ID of the audit log record to fetch the audit log
            details.
          schema:
            type: string
      responses:
        '200':
          description: Audit log details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogDetails'
              examples:
                AuditLogExample:
                  $ref: '#/components/examples/AuditLogDetailsExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                ErrorUnauthorizedExample:
                  $ref: '#/components/examples/ErrorUnauthorizedExample'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                ErrorForbiddenExample:
                  $ref: '#/components/examples/ErrorForbiddenExample'
        '404':
          description: Record Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseErrorWithDetails'
              examples:
                AuditLogNotFoundExample:
                  $ref: '#/components/examples/AuditLogNotFoundExample'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRetryDetails'
              examples:
                Internal-Server-Error:
                  $ref: '#/components/examples/InternalServerError'
components:
  securitySchemes:
    Bearer:
      description: >-
        Personal access token compliant with RFC8725 issued by the HPE GreenLake
        platform.
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    BaseError:
      type: object
      required:
        - errorCode
        - message
        - debugId
        - httpStatusCode
      properties:
        errorCode:
          type: string
          description: Unique machine-friendly identifier for the error.
        message:
          type: string
          description: User-friendly error message.
        debugId:
          type: string
          description: Unique identifier for the instance of this error.
        httpStatusCode:
          type: integer
          description: HTTP status code for the error.
    ErrorBadRequestDetails:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            errorDetails:
              description: Additional detailed information about the error.
              type: array
              items:
                required:
                  - type
                  - issues
                properties:
                  type:
                    type: string
                    default: hpe.greenlake.bad_request
                    description: Error type
                  issues:
                    type: array
                    description: List of bad request issues
                    items:
                      required:
                        - source
                        - subject
                      properties:
                        source:
                          type: string
                          description: The part of the request with an issue.
                        subject:
                          type: string
                          description: >-
                            The specific issue key. For example, if the source
                            property is field, the subject is the dot-separated
                            property name the issue is about
                        description:
                          type: string
                          description: A human-readable description of the issue.
    ErrorRetryDetails:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            errorDetails:
              description: Additional detailed information about the error.
              type: array
              items:
                required:
                  - type
                  - retryAfterSeconds
                properties:
                  type:
                    type: string
                  retryAfterSeconds:
                    type: integer
    ServiceOfferResponse:
      type: object
      description: Service offer details for which this audit log is published.
      required:
        - id
        - region
        - name
      properties:
        id:
          type: string
          description: Service offer ID.
          format: uuid
        name:
          type: string
          description: Service offer name.
        region:
          type: string
          description: Service offer region where it is provisioned.
    AuditLogQueryResponse:
      type: object
      required:
        - count
        - offset
        - total
        - remainingRecords
        - items
      properties:
        count:
          type: integer
          description: Number of items returned in the response.
        offset:
          type: integer
          description: Zero-based offset of the first item in the response.
        total:
          type: integer
          description: >-
            Total number of items matching the query. Maximum value is 10,000.
            If more than 10,000 items match the query, then remainingRecords is
            set to true.
        remainingRecords:
          type: boolean
          description: >-
            Boolean value indicating if there are more than 10,000 records
            available that match the query. Client can apply filters to narrow
            down the results.
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditLogItem'
    AuditLogItem:
      type: object
      required:
        - id
        - type
        - category
        - createdAt
        - description
        - username
        - serviceOffer
        - workspace
      properties:
        additionalInfo:
          $ref: '#/components/schemas/AuditLogAdditionalInfo'
        id:
          type: string
          format: uuid
        category:
          type: string
        createdAt:
          type: string
          format: date-time
        description:
          type: string
        hasDetails:
          type: boolean
        serviceOffer:
          $ref: '#/components/schemas/ServiceOfferResponse'
        type:
          type: string
        username:
          type: string
        workspace:
          $ref: '#/components/schemas/WorkspaceRef'
        ipAddress:
          type: string
          description: IPv4 or IPv6 address of the user who performed the action.
    AuditLogAdditionalInfo:
      type: object
      properties:
        deviceType:
          type: string
        serverName:
          type: string
        serverProductId:
          type: string
        serverSerial:
          type: string
    WorkspaceRef:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the workspace.
        name:
          type: string
          description: Name of the workspace where the audit log event occurred.
        type:
          type: string
          enum:
            - STANDALONE
            - TENANT
            - MSP
          description: Type of the workspace.
    AuditLogDetails:
      type: object
      required:
        - id
        - type
        - header
        - body
      properties:
        id:
          type: string
          format: uuid
          description: Audit log ID
        type:
          type: string
          default: /audit-log/log/details
          description: Resource type
        header:
          type: string
          description: Heading summarizing the audit log details.
        body:
          type: array
          items:
            type: string
          description: Array of action or detail strings describing the audit event.
    BaseErrorWithDetails:
      allOf:
        - $ref: '#/components/schemas/BaseError'
        - type: object
          properties:
            errorDetails:
              type: array
              items:
                type: object
                required:
                  - type
                  - source
                  - metadata
                properties:
                  type:
                    type: string
                  source:
                    type: string
                  metadata:
                    type: object
                    additionalProperties: true
  examples:
    AuditLogQueryResponseExample:
      summary: Example response for audit log query
      value:
        count: 3
        offset: 0
        total: 100
        remainingRecords: true
        items:
          - id: 8RtJaZQBITMTdBbBUxzz
            type: /audit-log/log
            serviceOffer:
              id: 68067533-5764-401a-9620-24e6e2cdc574
              name: Backup and Recovery
              region: us-east
            username: testuser@test.com
            category: Storage settings
            description: Storage firmware updated
            workspace:
              id: 3e35c938fb5911edbb4c660832a054ff
              name: workspace name
              type: STANDALONE
            createdAt: '2024-02-10T07:54:55.0Z'
            ipAddress: 192.168.11.21
            additionalInfo:
              serverName: test
            hasDetails: true
          - id: rEVHaZQBXE5qqlsVcfN3
            type: /audit-log/log
            serviceOffer:
              id: 00000000-0000-0000-0000-000000000000
              name: HPE Greenlake Platform
              region: global
            username: testuser@test.com
            category: Customer Management
            description: >-
              Loading workspace 3e35c938fb5911edbb4c660832a054ff for user
              testuser@test.com
            workspace:
              id: 3e35c938fb5911edbb4c660832a054ff
              name: workspace name
              type: STANDALONE
            createdAt: '2024-02-10T07:54:55.0Z'
            ipAddress: 192.168.11.11
            hasDetails: false
          - id: 9ztJaZqBITvbTdBbaUxzz
            type: /audit-log/log
            serviceOffer:
              id: d46569ae-0516-4dd2-81ce-b6d645842acc
              name: Compute Cloud Console
              region: us-west
            username: testuser@test.com
            category: ILO Settings
            description: Cloud Guest Activity
            workspace:
              id: 3e35c938fb5911edbb4c660832a054ff
              name: workspace name
              type: STANDALONE
            createdAt: '2024-02-10T07:54:55.0Z'
            ipAddress: 192.168.11.21
            additionalInfo:
              serverName: test
            hasDetails: true
    ErrorBadRequestExample:
      value:
        errorCode: HPE_GL_ERROR_BAD_REQUEST
        httpStatusCode: 400
        message: Bad request error
        debugId: abbeeb59-12cb-49a3-9ce5-55edba12213f
        errorDetails:
          - type: hpe.greenlake.bad_request
            issues:
              - source: hpe.greenlake.audit-log
                subject: select
                description: Unsupported select attributes are passed in query parameter.
    UnsupportedFilterParameterError:
      value:
        errorCode: HPE_GL_ERROR_BAD_REQUEST
        httpStatusCode: 400
        message: Bad request error
        debugId: 12ab34cd-5678-9012-3456-789012345678
        errorDetails:
          - type: hpe.greenlake.bad_request
            issues:
              - source: query.parameter
                subject: filter
                description: >-
                  Unsupported filter parameter 'invalidField' provided.
                  Supported parameters are createdAt, category, description,
                  ipAddress, username, workspace/name, workspace/type,
                  serviceOffer/id, region, hasDetails.
    InvalidRegionValueError:
      value:
        errorCode: HPE_GL_ERROR_BAD_REQUEST
        httpStatusCode: 400
        message: Bad request error
        debugId: 34ef56gh-7890-1234-5678-901234567890
        errorDetails:
          - type: hpe.greenlake.bad_request
            issues:
              - source: query.parameter
                subject: filter
                description: >-
                  Invalid region value 'invalid-region' provided. Supported
                  region codes include us-west, us-east, eu-central, etc.
    InvalidFilterOperatorError:
      value:
        errorCode: HPE_GL_ERROR_BAD_REQUEST
        httpStatusCode: 400
        message: Bad request error
        debugId: 56hi78jk-9012-3456-7890-123456789012
        errorDetails:
          - type: hpe.greenlake.bad_request
            issues:
              - source: query.parameter
                subject: filter
                description: >-
                  Invalid operator 'invalidOp' used in filter. Supported
                  operators are eq, in, contains, lt, ge.
    InvalidDateFormatError:
      value:
        errorCode: HPE_GL_ERROR_BAD_REQUEST
        httpStatusCode: 400
        message: Bad request error
        debugId: 78lm90no-3456-7890-1234-567890123456
        errorDetails:
          - type: hpe.greenlake.bad_request
            issues:
              - source: query.parameter
                subject: filter
                description: >-
                  Invalid date format 'invalid-date' provided for createdAt
                  filter. Expected RFC 3339 timestamp format (e.g.,
                  '2024-02-16T07:54:55.0Z').
    InvalidLimitValueError:
      value:
        errorCode: HPE_GL_ERROR_BAD_REQUEST
        httpStatusCode: 400
        message: Bad request error
        debugId: 90pq12rs-5678-9012-3456-789012345678
        errorDetails:
          - type: hpe.greenlake.bad_request
            issues:
              - source: query.parameter
                subject: limit
                description: >-
                  Invalid limit value '3000' provided. Maximum allowed limit is
                  2000.
    ErrorUnauthorizedExample:
      summary: Example unauthorized error
      value:
        errorCode: HPE_GL_ERROR_UNAUTHORIZED
        message: UNAUTHORIZED
        debugId: abbeeb59-12cb-49a3-9ce5-55edba12213f
        httpStatusCode: 401
        errorDetails:
          - type: hpe.greenlake.metadata
            source: hpe.greenlake.audit-log
            metadata:
              access_token: expired
    ErrorForbiddenExample:
      summary: Example forbidden error
      value:
        errorCode: HPE_GL_ERROR_FORBIDDEN
        message: FORBIDDEN
        debugId: abbeeb59-12cb-49a3-9ce5-55edba12213f
        httpStatusCode: 403
        errorDetails:
          - type: hpe.greenlake.metadata
            source: hpe.greenlake.audit-log
            metadata:
              access_token: invalid
    AuditLogItemExample:
      summary: Example audit log item
      value:
        id: 8RtJaZQBITMTdBbBUxzz
        type: /audit-log/log
        serviceOffer:
          id: 68067533-5764-401a-9620-24e6e2cdc574
          name: Backup and Recovery
          region: us-east
        username: testuser@test.com
        category: Storage settings
        description: Storage firmware updated
        workspace:
          id: 3e35c938fb5911edbb4c660832a054ff
          name: workspace name
          type: STANDALONE
        createdAt: '2024-02-10T07:54:55.0Z'
        ipAddress: 192.168.11.21
        additionalInfo:
          serverName: test
        hasDetails: true
    AuditLogDetailsExample:
      summary: Example audit log details
      value:
        id: 8RtJaZQBITMTdBbBUxzz
        type: /audit-log/log/details
        header: Storage Firmware Update
        body:
          - 'Firmware version: 1.2.3'
          - 'Update status: Successful'
    AuditLogNotFoundExample:
      summary: Example not found error
      value:
        errorCode: HPE_GL_ERROR_NOT_FOUND
        httpStatusCode: 404
        message: Audit details not found.
        debugId: 25e86df4-e2cd-4996-a2eb-895166174941
        errorDetails:
          - type: hpe.greenlake.not_found
            source: hpe.greenlake.audit-log
            metadata:
              id: not found
    TooManyRequestsError:
      value:
        errorCode: hpe.greenlake.too_many_requests
        message: Too many requests. Please try again later.
        debugId: 123123-12313-123123-123123
        httpStatusCode: 429
    InternalServerError:
      value:
        httpStatusCode: 500
        message: >-
          We encountered an unexpected server error. Please try again, and if
          the issue continues, reach out to us for assistance.
        errorCode: HPE_GL_ERROR_INTERNAL_SERVER_ERROR
        debugId: abbeeb59-12cb-49a3-9ce5-55edba12213f
        errorDetails:
          - type: hpe.greenlake.retry_info
            retryAfterSeconds: 30
