Palo Alto Networks Subscriptions API

openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Subscriptions 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: Subscriptions
  description: Subscription and license management.
paths:
  /subscriptions:
    get:
      operationId: listSubscriptions
      summary: Palo Alto Networks List Subscriptions for TSG
      description: Returns the active subscriptions for the specified Tenant Service Group. Each subscription entry includes the product SKU, licensed quantities, current utilization, and subscription term dates.
      tags:
      - Subscriptions
      parameters:
      - name: tsg_id
        in: query
        required: true
        description: Tenant Service Group ID for which to list subscriptions.
        schema:
          type: string
        example: '419008'
      - name: product
        in: query
        description: Filter subscriptions by product name.
        schema:
          type: string
        example: example-product
      - name: status
        in: query
        description: Filter subscriptions by status.
        schema:
          type: string
          enum:
          - active
          - expired
          - pending
        example: expired
      responses:
        '200':
          description: Subscriptions returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of subscriptions for the TSG.
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
              examples:
                ListSubscriptions200Example:
                  summary: Default listSubscriptions 200 response
                  x-microcks-default: true
                  value:
                    total: 549
                    items:
                    - subscription_id: '705492'
                      tsg_id: '889982'
                      product_name: Corporate Sensor 22
                      sku: example-sku
                      status: expired
                      licensed_quantity: 529
                      licensed_unit: example-licensed_unit
                      utilized_quantity: 615
                      start_date: '2024-07-22'
                      end_date: '2025-06-25'
                      support_level: example-support_level
        '400':
          description: Invalid query parameters or missing tsg_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListSubscriptions400Example:
                  summary: Default listSubscriptions 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListSubscriptions401Example:
                  summary: Default listSubscriptions 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListSubscriptions403Example:
                  summary: Default listSubscriptions 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ListSubscriptions500Example:
                  summary: Default listSubscriptions 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscriptions/{subscription_id}:
    get:
      operationId: getSubscription
      summary: Palo Alto Networks Get Subscription Details
      description: Returns full details for a specific subscription including product information, licensed capacity, current utilization, and term dates.
      tags:
      - Subscriptions
      parameters:
      - name: subscription_id
        in: path
        required: true
        description: Unique identifier of the subscription.
        schema:
          type: string
        example: '888186'
      responses:
        '200':
          description: Subscription details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
              examples:
                GetSubscription200Example:
                  summary: Default getSubscription 200 response
                  x-microcks-default: true
                  value:
                    subscription_id: '705492'
                    tsg_id: '889982'
                    product_name: Corporate Sensor 22
                    sku: example-sku
                    status: expired
                    licensed_quantity: 529
                    licensed_unit: example-licensed_unit
                    utilized_quantity: 615
                    start_date: '2024-07-22'
                    end_date: '2025-06-25'
                    support_level: example-support_level
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscription401Example:
                  summary: Default getSubscription 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscription403Example:
                  summary: Default getSubscription 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '404':
          description: Subscription not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscription404Example:
                  summary: Default getSubscription 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscription500Example:
                  summary: Default getSubscription 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscriptions/{subscription_id}/entitlements:
    get:
      operationId: getSubscriptionEntitlements
      summary: Palo Alto Networks Get Subscription Entitlement Details
      description: Returns the granular entitlement breakdown for a subscription including individual feature entitlements, allocated and available quantities per feature, and per-TSG allocation details.
      tags:
      - Subscriptions
      parameters:
      - name: subscription_id
        in: path
        required: true
        description: Unique identifier of the subscription.
        schema:
          type: string
        example: '922881'
      responses:
        '200':
          description: Entitlement details returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
              examples:
                GetSubscriptionEntitlements200Example:
                  summary: Default getSubscriptionEntitlements 200 response
                  x-microcks-default: true
                  value:
                    subscription_id: '110900'
                    product_name: Branch Firewall 98
                    entitlements:
                    - feature: example-feature
                      licensed_quantity: 149
                      allocated_quantity: 540
                      available_quantity: 678
                      unit: example-unit
                    - feature: example-feature
                      licensed_quantity: 722
                      allocated_quantity: 517
                      available_quantity: 547
                      unit: example-unit
                    allocations:
                    - tsg_id: '797363'
                      tsg_name: Primary Agent 81
                      allocated_quantity: 542
                      utilized_quantity: 137
                    - tsg_id: '990369'
                      tsg_name: Branch Gateway 87
                      allocated_quantity: 175
                      utilized_quantity: 129
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscriptionEntitlements401Example:
                  summary: Default getSubscriptionEntitlements 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscriptionEntitlements403Example:
                  summary: Default getSubscriptionEntitlements 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '404':
          description: Subscription not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscriptionEntitlements404Example:
                  summary: Default getSubscriptionEntitlements 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                GetSubscriptionEntitlements500Example:
                  summary: Default getSubscriptionEntitlements 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscriptions/{subscription_id}/allocation:
    put:
      operationId: allocateLicenses
      summary: Palo Alto Networks Allocate Licenses
      description: Allocates or reallocates license capacity from a subscription to specific child Tenant Service Groups. The total allocated quantity across all child TSGs cannot exceed the subscription's licensed quantity.
      tags:
      - Subscriptions
      parameters:
      - name: subscription_id
        in: path
        required: true
        description: Unique identifier of the subscription to allocate from.
        schema:
          type: string
        example: '302634'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationRequest'
            examples:
              AllocateLicensesRequestExample:
                summary: Default allocateLicenses request
                x-microcks-default: true
                value:
                  allocations:
                  - tsg_id: '560172'
                    quantity: 967
                  - tsg_id: '977953'
                    quantity: 890
      responses:
        '200':
          description: License allocation updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
              examples:
                AllocateLicenses200Example:
                  summary: Default allocateLicenses 200 response
                  x-microcks-default: true
                  value:
                    subscription_id: '110900'
                    product_name: Branch Firewall 98
                    entitlements:
                    - feature: example-feature
                      licensed_quantity: 149
                      allocated_quantity: 540
                      available_quantity: 678
                      unit: example-unit
                    - feature: example-feature
                      licensed_quantity: 722
                      allocated_quantity: 517
                      available_quantity: 547
                      unit: example-unit
                    allocations:
                    - tsg_id: '797363'
                      tsg_name: Primary Agent 81
                      allocated_quantity: 542
                      utilized_quantity: 137
                    - tsg_id: '990369'
                      tsg_name: Branch Gateway 87
                      allocated_quantity: 175
                      utilized_quantity: 129
        '400':
          description: Invalid allocation request or insufficient license capacity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AllocateLicenses400Example:
                  summary: Default allocateLicenses 400 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '401':
          description: Invalid or missing Bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AllocateLicenses401Example:
                  summary: Default allocateLicenses 401 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '403':
          description: Insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AllocateLicenses403Example:
                  summary: Default allocateLicenses 403 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '404':
          description: Subscription not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AllocateLicenses404Example:
                  summary: Default allocateLicenses 404 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                AllocateLicenses500Example:
                  summary: Default allocateLicenses 500 response
                  x-microcks-default: true
                  value:
                    error: example-error
                    message: Threat configured alert endpoint incident policy policy.
                    request_id: 5998b0f8-a299-4f51-b746-20623a02a65e
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Subscription:
      type: object
      properties:
        subscription_id:
          type: string
          description: Unique identifier of the subscription.
          example: '705492'
        tsg_id:
          type: string
          description: Tenant Service Group ID this subscription is associated with.
          example: '889982'
        product_name:
          type: string
          description: Product name (e.g., Prisma Access, Prisma SD-WAN).
          example: Corporate Sensor 22
        sku:
          type: string
          description: Product SKU identifier.
          example: example-sku
        status:
          type: string
          enum:
          - active
          - expired
          - pending
          description: Current subscription status.
          example: expired
        licensed_quantity:
          type: integer
          description: Total licensed quantity (e.g., number of users or devices).
          example: 529
        licensed_unit:
          type: string
          description: Unit of measure for the licensed quantity (e.g., users, devices, Mbps).
          example: example-licensed_unit
        utilized_quantity:
          type: integer
          description: Currently utilized quantity.
          example: 615
        start_date:
          type: string
          format: date
          description: Subscription start date.
          example: '2024-07-22'
        end_date:
          type: string
          format: date
          description: Subscription end date.
          example: '2025-06-25'
        support_level:
          type: string
          description: Support tier included with the subscription.
          example: example-support_level
    SubscriptionEntitlements:
      type: object
      properties:
        subscription_id:
          type: string
          description: Unique identifier of the subscription.
          example: '110900'
        product_name:
          type: string
          description: Product name.
          example: Branch Firewall 98
        entitlements:
          type: array
          description: Granular entitlements included in the subscription.
          items:
            $ref: '#/components/schemas/Entitlement'
          example:
          - feature: example-feature
            licensed_quantity: 149
            allocated_quantity: 540
            available_quantity: 678
            unit: example-unit
          - feature: example-feature
            licensed_quantity: 722
            allocated_quantity: 517
            available_quantity: 547
            unit: example-unit
        allocations:
          type: array
          description: Current license allocations by child TSG.
          items:
            $ref: '#/components/schemas/AllocationEntry'
          example:
          - tsg_id: '797363'
            tsg_name: Primary Agent 81
            allocated_quantity: 542
            utilized_quantity: 137
          - tsg_id: '990369'
            tsg_name: Branch Gateway 87
            allocated_quantity: 175
            utilized_quantity: 129
    AllocationRequest:
      type: object
      required:
      - allocations
      properties:
        allocations:
          type: array
          description: Array of TSG allocations to set. Each entry specifies a child TSG and the quantity to allocate to it. Existing allocations for TSGs not included in the array are unchanged.
          items:
            type: object
            required:
            - tsg_id
            - quantity
            properties:
              tsg_id:
                type: string
                description: Child TSG ID to allocate licenses to.
                example: '202659'
              quantity:
                type: integer
                description: Number of licenses to allocate to this TSG.
                minimum: 0
                example: 824
          example:
          - tsg_id: '560172'
            quantity: 967
          - tsg_id: '977953'
            quantity: 890
    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: Threat configured alert endpoint incident policy policy.
        request_id:
          type: string
          description: Request identifier for support correlation.
          example: 5998b0f8-a299-4f51-b746-20623a02a65e
    Entitlement:
      type: object
      properties:
        feature:
          type: string
          description: Feature or capability name.
          example: example-feature
        licensed_quantity:
          type: integer
          description: Licensed quantity for this entitlement.
          example: 755
        allocated_quantity:
          type: integer
          description: Quantity already allocated to child TSGs.
          example: 309
        available_quantity:
          type: integer
          description: Remaining quantity available for allocation.
          example: 585
        unit:
          type: string
          description: Unit of measure.
          example: example-unit
    AllocationEntry:
      type: object
      properties:
        tsg_id:
          type: string
          description: Child TSG ID receiving this allocation.
          example: '182151'
        tsg_name:
          type: string
          description: Display name of the child TSG.
          example: Primary Gateway 69
        allocated_quantity:
          type: integer
          description: Quantity allocated to this TSG.
          example: 389
        utilized_quantity:
          type: integer
          description: Quantity currently utilized by this TSG.
          example: 825
  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.