openapi: 3.1.0
info:
  title: Palo Alto Networks SASE Subscription Service API
  description: >-
    SASE Subscription Service API for license and subscription management.
    Provides visibility into active SASE subscriptions, entitlement details
    such as licensed user counts and feature entitlements, and license
    allocation controls for distributing capacity across Tenant Service
    Groups. Used by administrators to monitor license utilization and
    manage license distribution in multi-tenant SASE deployments.
  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.sase.paloaltonetworks.com/subscription/v1
  description: SASE Subscription Service 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: &id001
                    - 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: &id002
                    - 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: &id003
                  - 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: *id001
                    allocations: *id002
        '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:
  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.
  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: *id001
        allocations:
          type: array
          description: Current license allocations by child TSG.
          items:
            $ref: '#/components/schemas/AllocationEntry'
          example: *id002
    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
    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: *id003
    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