openapi: 3.0.0
info:
  title: Allocations API
  description: REST API to return device allocation details.
  version: 1.5.1
  contact:
    name: API Support
    url: https://www.watchguard.com/wgrd-support/contact-support
  termsOfService: https://www.watchguard.com/help/docs/api/Content/en-US/license_agreement.html?cshid=18007
paths:
  /health:
    get:
      description: HealthCheck URL
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/healthResponse'

  /v1/{accountId}/assets/{resourceType}:
    get:
      tags:
        - Allocation
      summary: Returns a list of assets.
      description: Returns a list of all assets (devices and software licenses) for
        your managed account.
      parameters:
        - name: accountId
          in: path
          description: |
            Identifies your WatchGuard Cloud account. Example: WGC-1-123abc456 or ACC-1234567.
          required: true
          schema:
            type: string
        - name: resourceType
          in: path
          description: |
            Type of asset.
          required: true
          schema:
            type: string
            enum:
              - accessPoint
              - firebox
              - fireboxRetention
              - TDR
              - authPoint
              - endPoint
        - name: selfAllocated
          in: query
          description: If set to true, returns only assets allocated to the account
            specified in the account ID parameter.
          required: false
          schema:
            type: boolean
        - name: sortBy
          in: query
          description: |
            Specifies how to sort results.
          required: false
          schema:
            type: string
            default: deviceName
            enum:
              - deviceName
              - licenseType
              - serialOrLicense
              - licenseExpiryDate
              - modelName
        - name: sortOrder
          in: query
          description: |
            Specifies how to order results. You can sort results in ascending or descending order.
              - asc - Sort results in ascending order.
              - desc - Sort results in descending order.
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: offset
          in: query
          description: Number of devices or licenses to skip before the API returns
            results.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: |
            Number of records to show on each page. A value of -1 shows all records.
          required: false
          schema:
            type: integer
            default: 25
            minimum: -1
        - in: query
          name: filterBy
          description: |
            Search string in deviceName, serialOrLicense, licenseType
          required: false
          schema:
            type: string
            default: ''
        - in: query
          name: aggregate
          description: Specifies whether you want an aggregate of all asset data returned.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful Response.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/accessPointResponse'
                  - $ref: '#/components/schemas/fireboxResponse'
                  - $ref: '#/components/schemas/fireboxRetentionResponse'
                  - $ref: '#/components/schemas/authPoint'
                  - $ref: '#/components/schemas/endPoint'
                  - $ref: '#/components/schemas/TDR'
        default:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
  /v1/{accountId}/assetsAllocation:
    get:
      tags:
        - Allocation
      summary: Returns a list of assets.
      description: Returns a hierarchy of all allocated assets (devices and software
        licenses) for your managed and delegated accounts.
      parameters:
        - name: accountId
          in: path
          description: |
            Identifies your WatchGuard Cloud account. Example: WGC-1-123abc456 or ACC-1234567.
          required: true
          schema:
            type: string
        - name: resourceType
          in: query
          description: |
            Type of asset.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - accessPoint
                - firebox
                - TDR
                - authPoint
                - endPoint
        - name: accountType
          in: query
          description: |
            Type of account.
          required: false
          schema:
            type: integer
            enum:
              - 1
              - 2
        - name: includeDelegatedAccounts
          in: query
          description: |
            Specifies whether delegated accounts are included in the response.
          required: false
          schema:
            type: boolean
            default: false
        - name: sortBy
          in: query
          description: |
            Specifies how to sort results.
          required: false
          schema:
            type: string
            default: accountName
            enum:
              - accountName
              - licenseType
              - expiryDate
              - quantity
        - name: sortOrder
          in: query
          description: |
            Specifies how to order results. You can sort results in ascending or descending order.
              - asc - Sort results in ascending order.
              - desc - Sort results in descending order.
          required: false
          schema:
            type: string
            default: asc
            enum:
              - asc
              - desc
        - name: offset
          in: query
          description: Number of devices or licenses to skip before the API returns
            results.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: |
            Number of records to show on each page. A value of -1 shows all records.
          required: false
          schema:
            type: integer
            default: 25
            minimum: -1
        - in: query
          name: filterBy
          description: |
            Search string in deviceName, serialOrLicense, licenseType.
          required: false
          schema:
            type: string
            default: ''
      responses:
        '200':
          description: Successful Response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAssetsAllocationPublicObject'
        default:
          description: Unexpected error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/errorResponse'
components:
  schemas:
    errorResponse:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: An absolute URI that identifies the type of error.
          default: about:blank
        title:
          type: string
          description: A descriptive title for the error.
        status:
          type: integer
          description: The HTTP status code generated by the server.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: A description of the error.
          example: Connection to the database timed out.
        instance:
          type: string
          format: uri
          description: An absolute URI that identifies the error.
    healthResponse:
      type: object
      required:
        - healthy
      properties:
        healthy:
          type: boolean
          default: false
        message:
          type: string
    deviceInfoObject:
      type: object
      properties:
        licenseType:
          description: Type of license or device.
          type: string
        accountId:
          description: WatchGuard Cloud account ID of the managed account.
          type: string
        accountName:
          description: WatchGuard Cloud account name of the managed account.
          type: string
        mac:
          description: Mac address of the device.
          type: string
        serialOrLicense:
          description: Serial number or license ID of the resource.
          type: string
        deviceName:
          description: Name of the device.
          type: string
        modelName:
          description: Model name of the device.
          type: string
        allocationDate:
          description: Allocation date.
          type: string
        daysUntilExpire:
          description: Number of days until the license expires.
          type: string
        allocationExpiryDate:
          description: Allocation expiration date.
          type: string
        licenseExpiryDate:
          description: License expiry date.
          type: string
    licenseInfoObject:
      type: object
      properties:
        accountId:
          description: WatchGuard Cloud account ID of the managed account.
          type: string
        accountName:
          description: WatchGuard Cloud account name of the managed account.
          type: string
        licenseType:
          description: License type of the asset.
          type: string
        serialOrLicense:
          description: Serial number or license ID of the resource.
          type: string
        allocationDate:
          description: Allocation date.
          type: string
        allocationExpiryDate:
          description: Allocation expiry date.
          type: string
        daysUntilExpire:
          description: Number of days before the license expires.
          type: string
        quantity:
          description: Total number of licenses in the owner account.
          type: integer
    pageControls:
      description: Settings that specify how to paginate search results.
      type: object
      properties:
        limit:
          description: Number of records to show per page. A value of -1 shows all
            records.
          type: integer
        offset:
          description: Number of the first record to include in the results.
          type: integer
        totalItems:
          description: Total number of records available.
          type: integer
    accessPointResponse:
      description: List of Wi-Fi access points allocated to the managed account.
      type: object
      properties:
        data:
          description: List with information about Wi-Fi access points allocated to
            the managed account.
          type: array
          items:
            $ref: '#/components/schemas/deviceInfoObject'
        pageControls:
          $ref: '#/components/schemas/pageControls'
    fireboxResponse:
      description: List of Fireboxes allocated to the managed account.
      type: object
      properties:
        data:
          description: List with information about Fireboxes allocated to the managed
            account.
          type: array
          items:
            $ref: '#/components/schemas/deviceInfoObject'
        pageControls:
          $ref: '#/components/schemas/pageControls'
    fireboxRetentionResponse:
      description: List of Firebox Data Retention licenses allocated to the managed
        account.
      type: object
      properties:
        data:
          description: List with information about Firebox Data Retention licenses
            allocated to the managed account.
          type: array
          items:
            $ref: '#/components/schemas/deviceInfoObject'
        pageControls:
          $ref: '#/components/schemas/pageControls'
    authPoint:
      description: List of AuthPoint licenses allocated to the managed account.
      type: object
      properties:
        data:
          description: List with information about AuthPoint licenses allocated to
            the managed account.
          type: array
          items:
            $ref: '#/components/schemas/licenseInfoObject'
        pageControls:
          $ref: '#/components/schemas/pageControls'
    endPoint:
      description: List of Endpoint licenses allocated to the managed account.
      type: object
      properties:
        data:
          description: List with information about Endpoint licenses allocated to
            the managed account.
          type: array
          items:
            $ref: '#/components/schemas/licenseInfoObject'
        pageControls:
          $ref: '#/components/schemas/pageControls'
    TDR:
      description: List of TDR licenses allocated to the managed account.
      type: object
      properties:
        data:
          description: List with information about TDR licenses allocated to the managed
            account.
          type: array
          items:
            $ref: '#/components/schemas/licenseInfoObject'
        pageControls:
          $ref: '#/components/schemas/pageControls'
    GetAssetInfoObject:
      type: object
      properties:
        accountType:
          description: Type of Account (1 - Service Provider children, 2 - Subscriber
            children).
          type: integer
        allocationDate:
          description: Allocation date.
          type: string
        allocationExpiryDate:
          description: Allocation expiry date.
          type: string
        licenseType:
          description: License type of the asset.
          type: string
        accountId:
          description: WatchGuard Cloud account ID of the managed account.
          type: string
        accountName:
          description: WatchGuard Cloud account name of the managed account.
          type: string
        quantity:
          description: Total number of licenses in the owner account.
          type: integer
        relationType:
          description: Type of relation (Delegated or Inherited).
          type: string
    GetAssetsAllocationPublicObject:
      description: List of assets.
      type: object
      properties:
        data:
          description: List of assets.
          type: array
          items:
            $ref: '#/components/schemas/GetAssetInfoObject'
        selfAllocatedAssets:
          description: A list of assets allocated to the owner's account.
          type: array
          items:
            $ref: '#/components/schemas/GetAssetInfoObject'
        pageControls:
          $ref: '#/components/schemas/pageControls'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: WatchGuard-API-Key
servers:
  - url: https://api.usa.cloud.watchguard.com/rest/platform/allocation
    description: Prod USA Region
  - url: https://api.deu.cloud.watchguard.com/rest/platform/allocation
    description: Prod DEU region
  - url: https://api.jpn.cloud.watchguard.com/rest/platform/allocation
    description: Prod JPN region
security:
  - ApiKeyAuth: []
    BearerAuth: []
externalDocs:
  description: Additional documentation
  url: https://www.watchguard.com/help/docs/api/Content/en-US/home.html
