openapi: 3.1.0
info:
  title: Palo Alto Networks SaaS Security API
  description: >-
    SaaS Security API (Aperture) for cloud application security. Provides
    programmatic access to security incidents, scanned assets, connected SaaS
    applications, user activity data, and log forwarding configuration.
    Enables security teams to automate incident response workflows, investigate
    exposed assets, and monitor user behavior across sanctioned SaaS
    applications including Google Workspace, Microsoft 365, Salesforce,
    Box, Dropbox, and other connected applications.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.aperture.paloaltonetworks.com
  description: SaaS Security (Aperture) API production server.
security:
- bearerAuth: []
tags:
- name: Applications
  description: Connected SaaS application management.
- name: Assets
  description: Scanned asset inventory and exposure analysis.
- name: Incidents
  description: Security incident management and status updates.
- name: Settings
  description: Log forwarding and configuration settings.
- name: Users
  description: User account and activity data.
paths:
  /api/incidents:
    get:
      operationId: listIncidents
      summary: Palo Alto Networks List Incidents
      description: >-
        Returns a paginated list of security incidents detected across
        connected SaaS applications. Supports filtering by status, severity,
        application, and date range. Incidents represent policy violations
        or anomalous activity such as external sharing of sensitive data,
        malware uploads, or configuration violations.
      tags:
      - Incidents
      parameters:
      - name: offset
        in: query
        description: Number of results to skip for pagination.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of incidents to return per page.
        schema:
          type: integer
          default: 50
          maximum: 200
        example: 50
      - name: status
        in: query
        description: Filter incidents by current status.
        schema:
          type: string
          enum:
          - new
          - in_progress
          - resolved
          - dismissed
        example: resolved
      - name: severity
        in: query
        description: Filter incidents by severity level.
        schema:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
        example: low
      - name: app_id
        in: query
        description: Filter incidents by SaaS application ID.
        schema:
          type: string
        example: '490106'
      - name: start_date
        in: query
        description: Filter incidents created on or after this date (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2025-11-22T11:53:29Z'
      - name: end_date
        in: query
        description: Filter incidents created on or before this date (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2024-08-28T03:48:57Z'
      responses:
        '200':
          description: Incidents returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of incidents matching the query.
                  offset:
                    type: integer
                  limit:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Incident'
              examples:
                ListIncidents200Example:
                  summary: Default listIncidents 200 response
                  x-microcks-default: true
                  value:
                    total: 706
                    offset: 152
                    limit: 817
                    items:
                    - id: example-id
                      title: Primary Agent 47
                      description: Investigation incident suspicious policy on applied alert endpoint traffic endpoint blocked violation.
                      status: resolved
                      severity: critical
                      app_id: '781451'
                      app_name: Staging Agent 76
                      policy_name: Branch Sensor 98
                      affected_assets: &id001
                      - example-affected_assets_item
                      - example-affected_assets_item
                      affected_users: &id002
                      - example-affected_users_item
                      assignee_id: '140527'
                      created_at: '2026-06-24T16:04:21Z'
                      updated_at: '2024-02-19T07:50:40Z'
                    - id: example-id
                      title: Primary Agent 47
                      description: Investigation incident suspicious policy on applied alert endpoint traffic endpoint blocked violation.
                      status: resolved
                      severity: critical
                      app_id: '781451'
                      app_name: Staging Agent 76
                      policy_name: Branch Sensor 98
                      affected_assets: *id001
                      affected_users: *id002
                      assignee_id: '140527'
                      created_at: '2026-06-24T16:04:21Z'
                      updated_at: '2024-02-19T07:50:40Z'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListIncidents400Example:
                  summary: Default listIncidents 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListIncidents401Example:
                  summary: Default listIncidents 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListIncidents403Example:
                  summary: Default listIncidents 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListIncidents500Example:
                  summary: Default listIncidents 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/incidents/{id}:
    get:
      operationId: getIncident
      summary: Palo Alto Networks Get Incident Details
      description: >-
        Returns complete details for a specific security incident including
        the affected assets, impacted users, policy violations triggered,
        timeline of events, and current remediation status.
      tags:
      - Incidents
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier of the incident.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Incident details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              examples:
                GetIncident200Example:
                  summary: Default getIncident 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    title: Primary Agent 47
                    description: Investigation incident suspicious policy on applied alert endpoint traffic endpoint blocked violation.
                    status: resolved
                    severity: critical
                    app_id: '781451'
                    app_name: Staging Agent 76
                    policy_name: Branch Sensor 98
                    affected_assets: *id001
                    affected_users: *id002
                    assignee_id: '140527'
                    created_at: '2026-06-24T16:04:21Z'
                    updated_at: '2024-02-19T07:50:40Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetIncident401Example:
                  summary: Default getIncident 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetIncident403Example:
                  summary: Default getIncident 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '404':
          description: Incident not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetIncident404Example:
                  summary: Default getIncident 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetIncident500Example:
                  summary: Default getIncident 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateIncident
      summary: Palo Alto Networks Update Incident
      description: >-
        Updates the status, assignee, or adds a note to an existing security
        incident. Use this endpoint to integrate SaaS Security into incident
        response workflows and SOAR playbooks.
      tags:
      - Incidents
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier of the incident to update.
        schema:
          type: string
        example: example-id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - new
                  - in_progress
                  - resolved
                  - dismissed
                  description: New status for the incident.
                assignee_id:
                  type: string
                  description: User ID to assign the incident to.
                note:
                  type: string
                  description: Text note to add to the incident timeline.
                  maxLength: 4096
            examples:
              UpdateIncidentRequestExample:
                summary: Default updateIncident request
                x-microcks-default: true
                value:
                  status: in_progress
                  assignee_id: '685364'
                  note: example-note
      responses:
        '200':
          description: Incident updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              examples:
                UpdateIncident200Example:
                  summary: Default updateIncident 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    title: Primary Agent 47
                    description: Investigation incident suspicious policy on applied alert endpoint traffic endpoint blocked violation.
                    status: resolved
                    severity: critical
                    app_id: '781451'
                    app_name: Staging Agent 76
                    policy_name: Branch Sensor 98
                    affected_assets: *id001
                    affected_users: *id002
                    assignee_id: '140527'
                    created_at: '2026-06-24T16:04:21Z'
                    updated_at: '2024-02-19T07:50:40Z'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdateIncident400Example:
                  summary: Default updateIncident 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdateIncident401Example:
                  summary: Default updateIncident 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdateIncident403Example:
                  summary: Default updateIncident 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '404':
          description: Incident not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdateIncident404Example:
                  summary: Default updateIncident 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UpdateIncident500Example:
                  summary: Default updateIncident 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/assets:
    get:
      operationId: listAssets
      summary: Palo Alto Networks List Scanned Assets
      description: >-
        Returns a paginated list of assets scanned across connected SaaS
        applications. Assets include files, folders, emails, and other content
        objects. Supports filtering by application, asset type, and exposure
        level indicating who can access the asset.
      tags:
      - Assets
      parameters:
      - name: app_id
        in: query
        description: Filter assets by SaaS application ID.
        schema:
          type: string
        example: '651878'
      - name: type
        in: query
        description: Filter by asset type.
        schema:
          type: string
          enum:
          - file
          - folder
          - email
          - calendar_event
          - contact
        example: file
      - name: exposure
        in: query
        description: Filter by exposure level.
        schema:
          type: string
          enum:
          - private
          - internal
          - external
          - public
        example: internal
      - name: offset
        in: query
        description: Number of results to skip for pagination.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of assets to return per page.
        schema:
          type: integer
          default: 50
          maximum: 200
        example: 50
      responses:
        '200':
          description: Assets returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Asset'
              examples:
                ListAssets200Example:
                  summary: Default listAssets 200 response
                  x-microcks-default: true
                  value:
                    total: 903
                    offset: 933
                    limit: 396
                    items:
                    - id: example-id
                      name: Production Policy 38
                      type: calendar_event
                      app_id: '972712'
                      app_name: Production Sensor 05
                      owner: example-owner
                      exposure: external
                      size_bytes: 550
                      dlp_violations: &id003
                      - example-dlp_violations_item
                      - example-dlp_violations_item
                      created_at: '2024-12-03T07:42:31Z'
                      updated_at: '2026-05-28T11:46:06Z'
                      last_scanned_at: '2026-10-13T08:39:47Z'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListAssets400Example:
                  summary: Default listAssets 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListAssets401Example:
                  summary: Default listAssets 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListAssets403Example:
                  summary: Default listAssets 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListAssets500Example:
                  summary: Default listAssets 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/assets/{id}:
    get:
      operationId: getAsset
      summary: Palo Alto Networks Get Asset Details
      description: >-
        Returns detailed information about a specific scanned asset including
        its current exposure, collaborators with access, DLP policy violations,
        and scan history.
      tags:
      - Assets
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier of the asset.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Asset details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
              examples:
                GetAsset200Example:
                  summary: Default getAsset 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    name: Production Policy 38
                    type: calendar_event
                    app_id: '972712'
                    app_name: Production Sensor 05
                    owner: example-owner
                    exposure: external
                    size_bytes: 550
                    dlp_violations: *id003
                    created_at: '2024-12-03T07:42:31Z'
                    updated_at: '2026-05-28T11:46:06Z'
                    last_scanned_at: '2026-10-13T08:39:47Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsset401Example:
                  summary: Default getAsset 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsset403Example:
                  summary: Default getAsset 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '404':
          description: Asset not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsset404Example:
                  summary: Default getAsset 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetAsset500Example:
                  summary: Default getAsset 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/applications:
    get:
      operationId: listApplications
      summary: Palo Alto Networks List Connected SaaS Applications
      description: >-
        Returns the list of SaaS applications connected to the SaaS Security
        tenant. Each application entry includes its connection status, the
        number of scanned assets, and the number of active incidents.
      tags:
      - Applications
      responses:
        '200':
          description: Connected applications returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
              examples:
                ListApplications200Example:
                  summary: Default listApplications 200 response
                  x-microcks-default: true
                  value:
                    total: 994
                    items:
                    - id: example-id
                      name: Primary Agent 80
                      type: advanced
                      status: connected
                      asset_count: 752
                      incident_count: 54
                      connected_at: '2025-07-22T17:44:41Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListApplications401Example:
                  summary: Default listApplications 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListApplications403Example:
                  summary: Default listApplications 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListApplications500Example:
                  summary: Default listApplications 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/users:
    get:
      operationId: listUsers
      summary: Palo Alto Networks List Users
      description: >-
        Returns the list of users discovered across connected SaaS applications.
        Includes user account details, access levels, and activity summaries.
      tags:
      - Users
      parameters:
      - name: app_id
        in: query
        description: Filter users by SaaS application.
        schema:
          type: string
        example: '860816'
      - name: offset
        in: query
        description: Number of results to skip for pagination.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of users to return.
        schema:
          type: integer
          default: 50
          maximum: 200
        example: 50
      responses:
        '200':
          description: Users returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
              examples:
                ListUsers200Example:
                  summary: Default listUsers 200 response
                  x-microcks-default: true
                  value:
                    total: 744
                    offset: 520
                    limit: 107
                    items:
                    - id: example-id
                      email: soc-admin@example.com
                      display_name: Sarah Doe
                      app_id: '562817'
                      account_type: internal
                      last_activity: '2025-01-07T13:18:09Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListUsers401Example:
                  summary: Default listUsers 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListUsers403Example:
                  summary: Default listUsers 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListUsers500Example:
                  summary: Default listUsers 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/user/{id}/activities:
    get:
      operationId: getUserActivities
      summary: Palo Alto Networks Get User Activity
      description: >-
        Returns the activity history for a specific user across connected SaaS
        applications. Activity includes file operations, sharing actions, login
        events, and policy-triggered events. Useful for user behavior analysis
        and insider threat investigations.
      tags:
      - Users
      parameters:
      - name: id
        in: path
        required: true
        description: Unique identifier of the user.
        schema:
          type: string
        example: example-id
      - name: start_date
        in: query
        description: Filter activities on or after this date (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2026-02-17T15:55:16Z'
      - name: end_date
        in: query
        description: Filter activities on or before this date (ISO 8601).
        schema:
          type: string
          format: date-time
        example: '2026-03-09T19:54:03Z'
      - name: app_id
        in: query
        description: Filter activities by SaaS application.
        schema:
          type: string
        example: '492712'
      - name: limit
        in: query
        description: Maximum number of activity records to return.
        schema:
          type: integer
          default: 100
          maximum: 500
        example: 100
      responses:
        '200':
          description: User activities returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserActivity'
              examples:
                GetUserActivities200Example:
                  summary: Default getUserActivities 200 response
                  x-microcks-default: true
                  value:
                    total: 127
                    items:
                    - id: example-id
                      user_id: '269446'
                      app_id: '356501'
                      action: drop
                      asset_id: '505071'
                      timestamp: '2026-12-27T04:51:36Z'
                      ip_address: 10.201.17.66
                      risk_level: low
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserActivities401Example:
                  summary: Default getUserActivities 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserActivities403Example:
                  summary: Default getUserActivities 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserActivities404Example:
                  summary: Default getUserActivities 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserActivities500Example:
                  summary: Default getUserActivities 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/settings/log-forwarding:
    get:
      operationId: getLogForwardingSettings
      summary: Palo Alto Networks Get Log Forwarding Settings
      description: >-
        Returns the current log forwarding configuration for the SaaS Security
        tenant, including enabled destinations such as syslog servers, SIEM
        integrations, and storage buckets.
      tags:
      - Settings
      responses:
        '200':
          description: Log forwarding settings returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogForwardingSettings'
              examples:
                GetLogForwardingSettings200Example:
                  summary: Default getLogForwardingSettings 200 response
                  x-microcks-default: true
                  value:
                    enabled: false
                    destinations: &id004
                    - type: s3
                      name: Staging Firewall 89
                      enabled: true
                      log_types:
                      - custom
                      - standard
                    - type: splunk
                      name: Staging Sensor 80
                      enabled: true
                      log_types:
                      - standard
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetLogForwardingSettings401Example:
                  summary: Default getLogForwardingSettings 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetLogForwardingSettings403Example:
                  summary: Default getLogForwardingSettings 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetLogForwardingSettings500Example:
                  summary: Default getLogForwardingSettings 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Configured monitoring network blocked investigation applied activity.
                    request_id: 5cc3d66e-5479-4e15-bd64-849adde3cb60
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 Bearer token. Obtain by authenticating with the SaaS
        Security API token endpoint using your service account credentials.
  schemas:
    Incident:
      type: object
      properties:
        id:
          type: string
          description: Unique incident identifier.
          example: example-id
        title:
          type: string
          description: Summary title of the incident.
          example: Primary Agent 47
        description:
          type: string
          description: Detailed description of the security incident.
          example: Investigation incident suspicious policy on applied alert endpoint traffic endpoint blocked violation.
        status:
          type: string
          enum:
          - new
          - in_progress
          - resolved
          - dismissed
          description: Current incident status.
          example: resolved
        severity:
          type: string
          enum:
          - low
          - medium
          - high
          - critical
          description: Incident severity level.
          example: critical
        app_id:
          type: string
          description: ID of the SaaS application where the incident occurred.
          example: '781451'
        app_name:
          type: string
          description: Name of the SaaS application.
          example: Staging Agent 76
        policy_name:
          type: string
          description: Name of the policy that triggered the incident.
          example: Branch Sensor 98
        affected_assets:
          type: array
          items:
            type: string
          description: IDs of assets involved in the incident.
          example: *id001
        affected_users:
          type: array
          items:
            type: string
          description: User IDs of users involved in the incident.
          example: *id002
        assignee_id:
          type: string
          description: User ID of the assigned analyst.
          example: '140527'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the incident was detected.
          example: '2026-06-24T16:04:21Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp of the most recent update.
          example: '2024-02-19T07:50:40Z'
    Asset:
      type: object
      properties:
        id:
          type: string
          description: Unique asset identifier.
          example: example-id
        name:
          type: string
          description: Asset name or filename.
          example: Production Policy 38
        type:
          type: string
          enum:
          - file
          - folder
          - email
          - calendar_event
          - contact
          description: Asset type.
          example: calendar_event
        app_id:
          type: string
          description: ID of the SaaS application containing the asset.
          example: '972712'
        app_name:
          type: string
          description: Name of the SaaS application.
          example: Production Sensor 05
        owner:
          type: string
          description: User ID of the asset owner.
          example: example-owner
        exposure:
          type: string
          enum:
          - private
          - internal
          - external
          - public
          description: Current exposure level of the asset.
          example: external
        size_bytes:
          type: integer
          description: Asset size in bytes.
          example: 550
        dlp_violations:
          type: array
          items:
            type: string
          description: DLP policy violation names triggered for this asset.
          example: *id003
        created_at:
          type: string
          format: date-time
          example: '2024-12-03T07:42:31Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-05-28T11:46:06Z'
        last_scanned_at:
          type: string
          format: date-time
          example: '2026-10-13T08:39:47Z'
    Application:
      type: object
      properties:
        id:
          type: string
          description: Unique application identifier.
          example: example-id
        name:
          type: string
          description: SaaS application name (e.g., Google Drive, Microsoft SharePoint).
          example: Primary Agent 80
        type:
          type: string
          description: Application type or category.
          example: advanced
        status:
          type: string
          enum:
          - connected
          - disconnected
          - error
          description: Current connection status.
          example: connected
        asset_count:
          type: integer
          description: Number of assets scanned for this application.
          example: 752
        incident_count:
          type: integer
          description: Number of active incidents for this application.
          example: 54
        connected_at:
          type: string
          format: date-time
          description: Timestamp when the application was connected.
          example: '2025-07-22T17:44:41Z'
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique user identifier.
          example: example-id
        email:
          type: string
          format: email
          description: User email address.
          example: soc-admin@example.com
        display_name:
          type: string
          description: User display name.
          example: Sarah Doe
        app_id:
          type: string
          description: SaaS application ID the user belongs to.
          example: '562817'
        account_type:
          type: string
          enum:
          - internal
          - external
          - service
          description: Type of user account.
          example: internal
        last_activity:
          type: string
          format: date-time
          description: Timestamp of the user's most recent activity.
          example: '2025-01-07T13:18:09Z'
    UserActivity:
      type: object
      properties:
        id:
          type: string
          description: Unique activity record identifier.
          example: example-id
        user_id:
          type: string
          description: ID of the user who performed the action.
          example: '269446'
        app_id:
          type: string
          description: SaaS application where the activity occurred.
          example: '356501'
        action:
          type: string
          description: Type of action performed (e.g., file_download, share_external).
          example: drop
        asset_id:
          type: string
          description: ID of the asset involved in the activity.
          example: '505071'
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the activity occurred.
          example: '2026-12-27T04:51:36Z'
        ip_address:
          type: string
          description: Source IP address of the activity.
          example: 10.201.17.66
        risk_level:
          type: string
          enum:
          - low
          - medium
          - high
          description: Risk level assigned to this activity.
          example: low
    LogForwardingSettings:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether log forwarding is globally enabled.
          example: false
        destinations:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - syslog
                - https
                - s3
                - splunk
                description: Forwarding destination type.
                example: s3
              name:
                type: string
                description: Destination name.
                example: Staging Policy 90
              enabled:
                type: boolean
                description: Whether this destination is active.
                example: true
              log_types:
                type: array
                items:
                  type: string
                description: Log types forwarded to this destination.
                example:
                - standard
          example: *id004
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code identifying the error type.
          example: example-error
        message:
          type: string
          description: Human-readable description of the error.
          example: Configured monitoring network blocked investigation applied activity.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: 5cc3d66e-5479-4e15-bd64-849adde3cb60