Allocations API (Deprecated)

Version 1 of the Allocations API is deprecated. Although v1 endpoints continue to accept requests, we strongly recommend that you use Version 2 of the Allocations API.

Version: 1.5.1

Allocations API Version History

Download the API specification

Introduction

The Allocations API is a RESTful API that you can use to return device and license allocation details for WatchGuard Cloud accounts that you manage.

This API documentation explains how to get access to the Allocations API and includes examples to help you get started.

Get Started

This section describes how to submit requests to the Allocations API.

The Allocations API URL is:

https://{base API URL}/rest/platform/allocation/

The base URL for WatchGuard public APIs varies by region. The base API URL for your account appears on the Managed Access page in WatchGuard Cloud.

Endpoint Path Parameters

Each WatchGuard public API has a version, expressed as <major>.<minor>.<patch>. You specify the major API version, such as v1, as part of the endpoint URI path.

Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. To use the Allocations API, you must first enable API access in your WatchGuard Cloud account and make an API request to generate an access token.

You must include the access token and your API Key in the header of each request you make to the Allocations API.

For more information, see Authentication.

Request Headers

You must include this information in the header of each request you make to the Allocations API:

Content-Type	application/json
Accept	application/json
Authorization	The access token that you generate with the WatchGuard Authentication API. For more information, see Authentication.
WatchGuard-API-Key	The API Key associated with your WatchGuard Cloud account (shown on the Managed Access page in WatchGuard Cloud).

Get Device or Software License Allocation List

/{v1}/{accountid}/assets/{resourceType}

Make a request to this endpoint to get a list of assets (devices and software licenses) allocated to your managed accounts.

Path Parameters

When you send a request to this endpoint, you must include these path parameters:

accountid
string
REQUIRED

Your WatchGuard Cloud account ID. You can see your accountId on the My Account page in WatchGuard Cloud.

Example: WGC-1-123abc456 or ACC-1234567

resourceType
string
REQUIRED

The type of asset to retrieve. Specify one of these values:

accessPoint — Retrieves a list of Wi-Fi access points.
firebox — Retrieves a list of Fireboxes.
fireboxRetention — Retrieves a list of Firebox Data Retention licenses.
TDR — Retrieves a list of TDR licenses.
authPoint - Retrieves a list of AuthPoint licenses.
endPoint - Retrieves a list of WatchGuard Endpoint Security licenses.

Example: accessPoint, firebox, TDR

Request Parameters

When you send a request to this endpoint, you can include these request parameters:

selfAllocated boolean	If set to true, returns only assets allocated to the account specified in the account ID parameter. The default value is false. Specify one of these values: true false Example: true
sortBy string	Specifies how to sort results. The default value is device name. Specify one of these values: deviceName — Sorts the results by device name. licenseType — Sorts the results by license type. serialOrLicense — Sorts the results by serial number or license ID. licenseExpiryDate — Sorts the results by license expiry date. modelName — Sorts the results by the model name of the device. Example: deviceName
sortOrder string	Specifies whether to sort the results in ascending or descending order. The default value is asc. Specify one of these values: asc — Sorts results in ascending order. desc — Sorts results in descending order. Example: asc
offset integer	Specifies the number of devices or licenses to skip before the API returns results. The default value is 1. Example: 25
limit integer	Specifies the number of records to show on each page. A value of -1 shows all records. The default value is 25. Example: 10
filterBy string	Filters by device name, serial or license number, or license type. If no filter parameter is specified, all records are returned. If a filter is specified, only filtered results are returned. The default behavior is that the request executes without the filter parameter. Example: serialOrLicense
aggregate boolean	Specifies whether to include an aggregate of all returned asset data in the response. Specify one of these values: true false Example: false

Example Request

This request returns a list of Firebox assets for account ID ACC-1234567:

curl -X GET 
	https://api.usa.cloud.watchguard.com/rest/platform/allocation/v1/ACC-1234567/assets/firebox?selfAllocated=true&sortBy=deviceName&sortOrder=asc&offset=1&limit=5&aggregate=false 
	-H 'Authorization: Bearer eyJraWQiOiJWamJQVlpnOU45SFRhdWJQZGVPU0d0WEdmbENTZnpRZ0E4NGdjTlRvN2ZjPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI0OGU1MjczOS1hNDlkLTQ1YTctODE5OS1iOGQzNTljMjhlYTIiLCJjdXN0b206YXBpX2tleXMiOiJiOVJoUGl4aTlUbE5qZDNQNDE0dXdrelUyVldGdzFjbGhTNktOenVMIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfeTBSamtRdkdqIiwiY29nbml0bzp1c2VybmFtZSI6IjkwYTMzYzdiMWJiNGJhYmFfcndfaWQiLCJhdWQiOiIxY3Y0aWRuYjhzb2M1ZWZtdHFxMHVqMDRkIiwiZXZlbnRfaWQiOiJhNDk4Y2ZkZS1jYTY0LTQyNDUtYjhhMC1jYjU0Njc2YmE4YjYiLCJ0b2tlbl91c2UiOiJpZCIsImN1c3RvbTpiZXRhX3ByZWZlcmVuY2VzIjoie1wiQUNDLTEyNzc5NDVcIjogW3tcImFwcGxpY2F0aW9uX2lkZW50aWZpZXJcIjogXCJ3Z2MtcGxhdGZvcm0tY29yZVwiLCBcImZlYXR1cmVfaWRlbnRpZmllclwiOiBcIm1mYS1vbi1hY2NvdW50c1wiLCBcImZlYXR1cmVfdmVyc2lvblwiOiBcIjEuMC4wXCJ9LCB7XCJhcHBsaWNhdGlvbl9pZGVudGlmaWVyXCI6IFwid2djLWF1dGhwb2ludFwiLCBcImZlYXR1cmVfaWRlbnRpZmllclwiOiBcImF1dGhwb2ludC11c2VyLWluaGVyaXRhbmNlXCIsIFwiZmVhdHVyZV92ZXJzaW9uXCI6IFwiMS4wLjBcIn0sIHtcImFwcGxpY2F0aW9uX2lkZW50aWZpZXJcIjogXCJEYXJrLVdlYi1Nb25pdG9yaW5nXCIsIFwiZmVhdHVyZV9pZGVudGlmaWVyXCI6IFwiXCIsIFwiZmVhdHVyZV92ZXJzaW9uXCI6IFwiXCJ9LCB7XCJhcHBsaWNhdGlvbl9pZGVudGlmaWVyXCI6IFwid2Vzcy1tb2R1bGVzXCIsIFwiZmVhdHVyZV9pZGVudGlmaWVyXCI6IFwiXCIsIFwiZmVhdHVyZV92ZXJzaW9uXCI6IFwiXCJ9LCB7XCJhcHBsaWNhdGlvbl9pZGVudGlmaWVyXCI6IFwiZG5zd2F0Y2gtYXBwbGljYXRpb25cIiwgXCJmZWF0dXJlX2lkZW50aWZpZXJcIjogXCJcIiwgXCJmZWF0dXJlX3ZlcnNpb25cIjogXCJcIn0sIHtcImFwcGxpY2F0aW9uX2lkZW50aWZpZXJcIjogXCJ3Z2MtYXV0aHBvaW50XCIsIFwiZmVhdHVyZV9pZGVudGlmaWVyXCI6IFwiYXV0aHBvaW50LWdlb2ZlbmNlLXBvbGljeVwiLCBcImZlYXR1cmVfdmVyc2lvblwiOiBcIjEuMC4wXCJ9LCB7XCJhcHBsaWNhdGlvbl9pZGVudGlmaWVyXCI6IFwiZmJ4LWNsb3VkLW1nbXQtMFwiLCBcImZlYXR1cmVfaWRlbnRpZmllclwiOiBcImNvbmYtZGlmZi1yZXBvcnRcIiwgXCJmZWF0dXJlX3ZlcnNpb25cIjogXCIxLjAuMFwifSwge1wiYXBwbGljYXRpb25faWRlbnRpZmllclwiOiBcImZieC1tZ210LXN5c3RlbS1hY3Rpb25zXCIsIFwiZmVhdHVyZV9pZGVudGlmaWVyXCI6IFwiZmJ4LWZ3LWJldGEtYnVpbGRzXCIsIFwiZmVhdHVyZV92ZXJzaW9uXCI6IFwiMS4wLjBcIn1dfSIsImF1dGhfdGltZSI6MTYyNDk3NTc2OCwibmFtZSI6IjkwYTMzYzdiMWJiNGJhYmFfcndfaWQiLCJjdXN0b206YWNjb3VudF9pZCI6IkFDQy0xMjc3OTQ1IiwiZXhwIjoxNjI0OTc5MzY4LCJjdXN0b206cm9sZSI6IjEiLCJpYXQiOjE2MjQ5NzU3Njh9.ofkgu5a2c-ViLJO1EkAT8-EcIkNWsLYqBOY9mIONEd5Lo3C27Mv3BpSxS1C35vrLN89Fo6YDb36DpZQVdZIZ5biOPAlDsY-wGx_kiDbNDOHvg4Sl9dZr_tZFs3yP3AikYH6oneNjnAaHL3OQCcEhQLUejhOsNf1NOPH2QQXovtfRxomygkZtngPZq4ATy_oDlXnzFA9ThXc7HjZ54aAJ9Z4p5-lJbHuwtpwpvLh6036_8Ba5yaD3r1ZuTghMRHprTVJNm2QrRDKd3jTfr7Sh87gAzRu80PHeZGsoiDQNssinxQxjVLI1Gq9vSPh03ZV01q9Pa5Xgg4WGkYHc2UKUuw' \
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: b9RhPixi9TlNjd3P414uwkzU2VWFw1clhS6KNzuL'

Example Response

{
    "data": [
        {
            "accountId": "ACC-1234567",
            "accountName": "GoodCompany1-1",
            "allocationDate": "2021-06-04T20:04:57Z",
            "allocationExpiryDate": "2999-12-31",
            "daysUntilExpire": 357176,
            "deviceName": "Firebox Demo",
            "licenseExpiryDate": "2019-10-01T00:00:00Z",
            "licenseType": "firebox",
            "mac": "25:C4:B5:C2:B3:2D",
            "modelName": "M200",
            "serialOrLicense": "0000ACC-1234567"
        },
        {
            "accountId": "ACC-1234567",
            "accountName": "GoodCompany1-1",
            "allocationDate": "2021-06-04T20:05:08Z",
            "allocationExpiryDate": "2999-12-31",
            "daysUntilExpire": 357176,
            "deviceName": "testFb1",
            "licenseExpiryDate": "2019-10-01T00:00:00Z",
            "licenseType": "firebox",
            "mac": "25:C4:B5:C2:B3:2D",
            "modelName": "M300",
            "serialOrLicense": "ABCTESTDEV-3"
        },
        {
            "accountId": "ACC-1234567",
            "accountName": "GoodCompany1-1",
            "allocationDate": "2021-06-04T20:05:16Z",
            "allocationExpiryDate": "2999-12-31",
            "daysUntilExpire": 357176,
            "deviceName": "testfb2",
            "licenseExpiryDate": "2019-10-01T00:00:00Z",
            "licenseType": "firebox",
            "mac": "00:90:7F:BD:CB:CF",
            "modelName": "M400",
            "serialOrLicense": "467TESTDEV-3"
        },
        {
            "accountId": "ACC-1234567",
            "accountName": "GoodCompany1-1",
            "allocationDate": "2019-11-13T11:00:54Z",
            "allocationExpiryDate": "2019-11-30",
            "daysUntilExpire": -793,
            "deviceName": "testFb3",
            "licenseExpiryDate": "2018-12-07T01:34:29Z",
            "licenseType": "firebox",
            "mac": "00:90:7F:BD:CB:CA",
            "modelName": "FireboxV Small",
            "serialOrLicense": "2222ACC-1234567"
        },
        {
            "accountId": "ACC-1234567",
            "accountName": "GoodCompany1-1",
            "allocationDate": "2020-12-10T16:19:40Z",
            "allocationExpiryDate": "2021-05-31",
            "daysUntilExpire": -245,
            "deviceName": "testFb4",
            "licenseExpiryDate": "2021-12-07T01:34:29Z",
            "licenseType": "firebox",
            "mac": "00:90:7F:BD:CB:D9",
            "modelName": "M200",
            "serialOrLicense": "0000ACC123-4567"
        }
    ],
    "pageControls": {
        "limit": 5,
        "offset": 1,
        "totalItems": 23
    }
}

This table shows and describes the data returned in the response:

data array	Array of asset or license data.
accountId string	WatchGuard Cloud account ID of the managed account. Example: WGC-1-123abc456
accountName string	WatchGuard Cloud account name of the managed account. Example: California Company
allocationDate string	Allocation date. Example: 2021-06-24T16:18:24Z
allocationExpiryDate string	Allocation expiration date. If you set the expiration date to Never, the date is 3000-01-01. Example: 3000-01-01
daysUntilExpire string	Number of days until the license expires. If the license has expired, this number will be a negative number. Example: 90
licenseType string	Type of device or license. This can be one of these values: firebox fireboxRetention accessPoint AuthPoint AuthPoint_Subscription AuthPoint_Trial AuthPoint_NFR WES WES_EPP WES_EPP_Subscription WES_EPP_Trial WES_EPP_NFR WES_EDR WES_EDR_Subscription WES_EDR_Trial WES_EDR_NFR WES_EPDR WES_EPDR_Subscription WES_EPDR_Trial WES_EPDR_NFR WES_Module_Advanced_Reporting_Tool WES_Module_Data_Control WES_Module_Full_Encryption WES_Module_Patch_Management WES_Module_SIEMFeeder WES_Module_ART_NFR WES_Module_Data_Control_NFR WES_Module_Full_Encryption_NFR WES_Module_SIEMFeeder_NFR WES_Module_Patch_Management_NFR WES_Module_ART_Subscription WES_Module_Data_Control_Subscription WES_Module_Full_Encryption_Subscription WES_Module_SIEMFeeder_Subscription WES_Module_Patch_Management_Subscription WES_Module_ART_Trial WES_Module_Data_Control_Trial WES_Module_Full_Encryption_Trial WES_Module_SIEMFeeder_Trial WES_Module_Patch_Management_Trial TDR Example: Firebox
quantity string	Total number of licenses allocated to the account. Example: 76
serialOrLicense string	Serial number or license ID of the asset. Example: WGAUTH351-1-B888889-B6606192
pageControls object	Settings that specify how to paginate search results.
limit integer	Number of records to show on each page. A value of -1 shows all records. Example: 25
offset integer	Number of the first record to include in the results. Example: 1
totalItems integer	Total number of records available. Example: 5

Get Asset Allocation List for Managed and Delegated Accounts

/{v1}/{accountid}/assetsAllocation

If you have a Service Provider account, you can make a request to this endpoint to get a hierarchy of all assets (devices and software licenses) allocated to managed and delegated accounts.