SaaS Security API

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: [email protected]
                      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/jso

# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-saas-security-api-openapi-original.yml