openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Users API
  description: AIOps for NGFW Best Practice Assessment (BPA) API. Provides programmatic access to submit BPA requests for Palo Alto Networks next-generation firewalls, check request processing status, and retrieve completed assessment reports. BPA reports analyze firewall configurations against Palo Alto Networks best practices and security benchmarks, identifying gaps and providing remediation guidance to improve security posture. Part of the Strata Cloud Manager platform.
  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.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
security:
- oauth2Bearer: []
tags:
- name: Users
  description: Browser user management and session visibility.
paths:
  /v1/users:
    get:
      operationId: listBrowserUsers
      summary: Palo Alto Networks List Browser Users
      description: Returns the list of users enrolled in the Prisma Access Browser. Includes user identity information, assigned policy, and current active session count.
      tags:
      - Users
      parameters:
      - name: policy_id
        in: query
        description: Filter users by assigned browser policy.
        schema:
          type: string
        example: '645121'
      - 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: Browser 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/BrowserUser'
              examples:
                ListBrowserUsers200Example:
                  summary: Default listBrowserUsers 200 response
                  x-microcks-default: true
                  value:
                    total: 828
                    offset: 606
                    limit: 36
                    items:
                    - user_id: '519106'
                      email: jane.doe@example.com
                      display_name: Carlos Doe
                      policy_id: '550297'
                      active_sessions: 493
                      last_active_at: '2024-12-26T17:43:03Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListBrowserUsers401Example:
                  summary: Default listBrowserUsers 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListBrowserUsers403Example:
                  summary: Default listBrowserUsers 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListBrowserUsers500Example:
                  summary: Default listBrowserUsers 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/users/{user_id}/sessions:
    get:
      operationId: getUserSessions
      summary: Palo Alto Networks Get User Sessions
      description: Returns the active and recent browser sessions for a specific user. Session data includes device, IP address, policy applied, and session duration.
      tags:
      - Users
      parameters:
      - name: user_id
        in: path
        required: true
        description: Unique identifier of the browser user.
        schema:
          type: string
        example: '194968'
      - name: status
        in: query
        description: Filter sessions by status.
        schema:
          type: string
          enum:
          - active
          - terminated
        example: active
      - name: limit
        in: query
        description: Maximum number of sessions to return.
        schema:
          type: integer
          default: 50
          maximum: 200
        example: 50
      responses:
        '200':
          description: User sessions returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrowserSession'
              examples:
                GetUserSessions200Example:
                  summary: Default getUserSessions 200 response
                  x-microcks-default: true
                  value:
                    total: 788
                    items:
                    - session_id: '926940'
                      user_id: '494860'
                      device_id: '107670'
                      ip_address: 10.108.68.13
                      policy_id: '176224'
                      browser_version: 4.0.8
                      status: active
                      started_at: '2024-10-10T11:55:14Z'
                      ended_at: '2026-07-09T16:25:54Z'
                    - session_id: '926940'
                      user_id: '494860'
                      device_id: '107670'
                      ip_address: 10.108.68.13
                      policy_id: '176224'
                      browser_version: 4.0.8
                      status: active
                      started_at: '2024-10-10T11:55:14Z'
                      ended_at: '2026-07-09T16:25:54Z'
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserSessions401Example:
                  summary: Default getUserSessions 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserSessions403Example:
                  summary: Default getUserSessions 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserSessions404Example:
                  summary: Default getUserSessions 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetUserSessions500Example:
                  summary: Default getUserSessions 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Suspicious detected incident malware activity traffic traffic.
                    request_id: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
      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_2'
              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_2'
              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_2'
              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_2'
              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_2'
              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_2'
              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_2'
              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
components:
  schemas:
    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
    BrowserUser:
      type: object
      properties:
        user_id:
          type: string
          description: Unique identifier of the browser user.
          example: '519106'
        email:
          type: string
          format: email
          description: User email address.
          example: jane.doe@example.com
        display_name:
          type: string
          description: User display name.
          example: Carlos Doe
        policy_id:
          type: string
          description: ID of the browser policy assigned to this user.
          example: '550297'
        active_sessions:
          type: integer
          description: Current number of active browser sessions.
          example: 493
        last_active_at:
          type: string
          format: date-time
          example: '2024-12-26T17:43:03Z'
    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: Suspicious detected incident malware activity traffic traffic.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: a6ecb027-74a1-4efb-9882-cb98e9bab4bf
    BrowserSession:
      type: object
      properties:
        session_id:
          type: string
          description: Unique identifier of the browser session.
          example: '926940'
        user_id:
          type: string
          description: User ID of the session owner.
          example: '494860'
        device_id:
          type: string
          description: Device ID used in this session.
          example: '107670'
        ip_address:
          type: string
          description: Client IP address.
          example: 10.108.68.13
        policy_id:
          type: string
          description: Policy applied during this session.
          example: '176224'
        browser_version:
          type: string
          description: Prisma Access Browser version.
          example: 4.0.8
        status:
          type: string
          enum:
          - active
          - terminated
          description: Session status.
          example: active
        started_at:
          type: string
          format: date-time
          example: '2024-10-10T11:55:14Z'
        ended_at:
          type: string
          format: date-time
          example: '2026-07-09T16:25:54Z'
    ErrorResponse_2:
      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
  securitySchemes:
    oauth2Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for SASE platform authentication. Obtain using the client_credentials grant with your SASE service account client ID and client secret.