Firebox Management API

Introduction

The Firebox Management API is a RESTful API that you can use to manage and configure Fireboxes that are associated with your WatchGuard Cloud account.

You can use the Firebox Management API to:

Add blocked sites and manage the Blocked Sites list
Create and manage different types of exceptions
Deploy configuration changes to Fireboxes

You can use the Firebox Management API to manage only Fireboxes in your WatchGuard Cloud account that run Fireware v12.5.3 or higher. To add a Firebox to your WatchGuard Cloud account, follow the steps in Add a Firebox to WatchGuard Cloud.

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

Get Started

This section describes how to submit requests to the Firebox Management API.

The Firebox Management API URL is:

https://{base API URL}/rest/firebox/management/

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.

All Firebox Management API endpoint URIs must include your WatchGuard Cloud account ID in the {accountid} path parameter.

Authentication

WatchGuard public APIs use the Open Authorization (OAuth) 2.0 authorization framework for token-based authentication. To use the Firebox Management 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 Firebox Management API.

For more information, see Authentication.

Request Headers

You must include this information in the header of each request you make to the Firebox Management 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).

Pagination

Some GET endpoints that return a list of objects support pagination through the limit and start_after request parameters:

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

You can use these parameters to construct queries for pages of results.

Exceptions

Exceptions are rules that bypass or override the other settings defined in your Firebox configuration. For example, you might define an exception because you do not want the Firebox to deny access to your company website. Or you might want the Firebox to always allow your users to download a specific file.

You can use the Firebox Management API to create these types of exceptions:

Blocked Sites and Blocked Sites Exceptions
Botnet Exceptions
File Exceptions
Geolocation Exceptions
Intrusion Prevention Service (IPS) Exceptions
WebBlocker Exceptions

When you create an exception with the API, you specify details of the exception, such as the address of a site you always want to block, and the device the exception applies to. The Firebox Management API saves the exceptions you configure to your WatchGuard Cloud account.

To configure an exception, make a request to the POST endpoint for that type of exception. To update or delete exceptions, make requests to the PUT and DELETE endpoints for each type of exception.

If you want to use the Firebox Management API to manage exceptions, we recommend that you add your Firebox to WatchGuard Cloud as a cloud-managed device. Before you can deploy the exceptions from your WatchGuard Cloud account to a locally-managed device, you must enable global exceptions for that device. The Firebox Management API includes two endpoints to enable and disable global exceptions for specified devices. For cloud-managed devices, you do not have to enable global exceptions to deploy exceptions to the device.

To update the device with the blocked sites and exceptions saved in your WatchGuard Cloud account, you must deploy the exceptions to the device. You can deploy exceptions immediately or schedule the deployment for a time in the future. For more information, see Deployments.

The Firebox applies all blocked sites and exceptions you save to the device with the Firebox Management API and Fireware (locally-managed devices) or WatchGuard Cloud (cloud-managed devices). For locally-managed devices, blocked sites and exceptions you configure with the Firebox Management API do not currently appear in Fireware Web UI or Policy Manager.

Endpoints:

/{v2}/configuration/{accountid}/exceptions

/{v1}/commands/{accountid}/global_exceptions/enable

/{v1}/commands/{accountid}/global_exceptions/disable

Query All Exceptions

WatchGuard Cloud stores any exceptions you create with the Firebox Management API. Make a request to this endpoint to retrieve all exceptions associated with your WatchGuard Cloud account. If you want to retrieve only specific exceptions, include the query request parameter.

Version 2

/{v2}/configuration/{accountid}/exceptions

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

Request Parameters

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

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

Example Request

This request retrieves blocked sites exceptions with an action of allow from the specified WatchGuard Cloud account.

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v2/configuration/WGC-1-123abc456/exceptions?limit=10&query=object:"blockedsite_exception" AND action:"allow"&start_after=bse_12345_ARBHLJ70Y78rGOIGBS  
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes an array of exceptions that match your query. The response includes only the highest version of each exception.

{
"count": 10,
"more": true,
"objects":[
{
"object": "blockedsite_exception",
"description": "Allow 192.0.2.1",
"device": 12345,
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
	},
"account": "WGC-1-123abc456",
"author": "",
"created": 1582316606,
"version": 1,
"action": "allow",
"id": "bse_12345_ARBHLJ70Y78rGOIGBS"
},
{
"object": "blockedsite_exception",
"description": "Allow example.com",
"device": 12345,
"address": {
	"type": "fqdn",
	"value": "*.example.com"
	},
"account": "WGC-1-123abc456",
"author": "",
"created": 1582299996,
"version": 1,
"action": "allow",
"id": "bse_12345_EU03pOyqJT1m32k23H"
},
...
],
"start_after": "bse_12345_ARBHLJ70Y78rGOIGBS"

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

count integer	Number of exceptions returned in the response. Example: 10
more boolean	If the `limit` parameter was specified in the request, this parameter indicates whether more exceptions match the query after the exceptions returned in this response. Example: true
objects array	List of exceptions associated with the specified WatchGuard Cloud account that match the query string. The parameters in each exception vary by the type of exception. For more information, see the GET endpoint for that type of exception.
start_after string	If the value of the `more` parameter is true, specifies the ID of the exception to use in another request to retrieve the next page of exceptions. Example: bse_13929_7XsCmfQFvN5uxfrsvY

Version 1 (Deprecated)

/{v1}/configuration/{accountid}/exceptions

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

Request Parameters

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

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

Example Request

This request retrieves all blocked sites exceptions with an action of allow from the specified WatchGuard Cloud account.

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions?query=object:"blockedsite_exception" AND action:"allow"  
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes an array of exceptions that match your query. The response includes only the highest version of each exception.

[
{
"object": "blockedsite_exception",
"description": "Allow 192.0.2.1",
"device": 12345,
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
	},
"account": "WGC-1-123abc456",
"author": "",
"created": 1582316606,
"version": 1,
"action": "allow",
"id": "bse_12345_ARBHLJ70Y78rGOIGBS"
},
{
"object": "blockedsite_exception",
"description": "Allow example.com",
"device": 12345,
"address": {
	"type": "fqdn",
	"value": "*.example.com"
	},
"account": "WGC-1-123abc456",
"author": "",
"created": 1582299996,
"version": 1,
"action": "allow",
"id": "bse_12345_EU03pOyqJT1m32k23H"
}
]

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

exceptions
array

List of exceptions associated with the specified WatchGuard Cloud account that match the query string.

The parameters in each exception vary by the type of exception. For more information, see the GET endpoint for that type of exception.

Enable Global Exceptions

/{v1}/commands/{accountid}/global_exceptions/enable

Make a request to this endpoint to enable global exceptions for the specified locally-managed devices.

When you enable global exceptions for a locally-managed device, the Firebox Management API checks if your WatchGuard Cloud account includes exceptions for the device. If exceptions exist for the device in WatchGuard Cloud, the API creates a device deployment and automatically deploys the exceptions to the device.

Only enable global exceptions for locally-managed devices. For cloud-managed devices, you do not have to enable global exceptions to deploy the exceptions in WatchGuard Cloud to the device.

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

Request Body

devices
array
REQUIRED

Device(s) to enable global exceptions for.

Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, your device ID is FB-12345.

For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345.

For FireClusters, specify the full device ID. For example, FBCL-12345.

Enclose in square brackets and separate device IDs with commas.

Example: [12345,12346,12347]

You can specify a maximum of 50 devices in the list.

Example Request

This request enables global exceptions for two devices:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/WGC-1-123abc456/global_exceptions/enable 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"devices":[12345,67890]
	}'

Example Response

A successful request returns the 204 No Content status code.

Disable Global Exceptions

/{v1}/commands/{accountid}/global_exceptions/disable

Make a request to this endpoint to disable global exceptions for the specified locally-managed devices.

When you disable global exceptions for a locally-managed device, by default the Firebox Management API removes any exceptions configured with the API from the locally-managed device. To retain the exceptions on the device, specify true as the value of the optional retain_device_configuration parameter in the request body. Requests to this endpoint do not delete exceptions from the locally-managed device that were configured with Fireware.

When you disable global exceptions for a locally-managed device, the Firebox Management API does not delete exceptions from WatchGuard Cloud for the device. If you make a subsequent request to the /{v1}/commands/{accountid}/global_exceptions/enable endpoint, the Firebox Management API redeploys any exceptions in WatchGuard Cloud back to the device. To delete an exception from WatchGuard Cloud, make a request to the DELETE endpoint for that type of exception.

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

Request Body

devices
array
REQUIRED

Device(s) to disable global exceptions for.

For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345.

For FireClusters, specify the full device ID. For example, FBCL-12345.

Enclose in square brackets and separate device IDs with commas.

Example: [12345,12346,12347]

You can specify a maximum of 50 devices in the list.

Example Request

This request disables global exceptions for two devices, and deletes any exceptions configured with the Firebox Management API from the device:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/WGC-1-123abc456/global_exceptions/disable 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"retain_device_configuration": false,
	"devices":[12345,67890]
	}'

Example Response

A successful request returns the 204 No Content status code.

Blocked Sites and Blocked Sites Exceptions

A blocked site is an IP address that cannot make a connection through the Firebox. The Firebox denies connections to or from blocked sites.

Users can add sites permanently to the Blocked Sites list in Fireware. The Firebox also adds sites to the Blocked Sites list temporarily based on the rules defined in policies.

If the Firebox blocks connections to a site users believe to be safe, they can add the site to the Blocked Sites Exceptions list, so that traffic from that site is not blocked.

You can use Firebox Management API to add a site to either the Blocked Sites list or the Blocked Sites Exceptions list. The value of the action parameter in the blocked sites exception object specifies which list to add the site to. Allow adds the address to the Blocked Sites Exception list. Block adds the address to the Blocked Sites list.

For more information about blocked sites and blocked sites exceptions, see About Blocked Sites in Fireware Help.

Endpoints:

/{v2}/configuration/{accountid}/exceptions/blockedsite

/{v1}/configuration/{accountid}/exceptions/blockedsite

/{v1}/configuration/{accountid}/exceptions/blockedsite/{objectid}

Query All Blocked Sites and Blocked Sites Exceptions

WatchGuard Cloud stores any blocked sites and blocked sites exceptions you create with the Firebox Management API. Make a request to this endpoint to retrieve all blocked sites and blocked sites exceptions associated with your WatchGuard Cloud account. If you want to retrieve only specific blocked sites or blocked sites exceptions, include the query request parameter.

Version 2

/{v2}/configuration/{accountid}/exceptions/blockedsite

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

Request Parameters

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

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

Example Request

This request retrieves blocked sites and blocked sites exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v2/configuration/WGC-1-123abc456/exceptions/blockedsite?limit=10&query=device:12345 AND action:"allow"&start_after=bse_12345_ARBHLJ70Y78rGOIGBS  
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes an array that lists all blocked sites and blocked sites exceptions that match the specified query. The response includes only the highest version of each exception.

{
"count": 10,
"more": true,
"objects": [
{
"object": "blockedsite_exception",
"description": "Allow 192.0.2.1",
"device": 12345,
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
},
"account": "WGC-1-123abc456",
"author": ""
"created": 1580159344,
"version": 1,
"action": "allow",
"id": "bse_12345_EU03pOyqJT1m32k23H",
},
{
"object": "blockedsite_exception",
"description": "Block example.com",
"device": 12345,
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"account": "WGC-1-123abc456",
"author": ""
"created": 1580160941,
"version": 1,
"action": "block",
"id": "bse_12345_GU56oOcfHD4n56s27O",
}
...					
],
"start_after": "bse_12345_ARBHLJ70Y78rGOIGBS"
}

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

count integer	Number of exceptions returned in the response. Example: 10
more boolean	If the `limit` parameter was specified in the request, this parameter indicates whether more exceptions match the query after the exceptions returned in this response. Example: true
ojects array	List of blocked sites exceptions.
object string	Type of exception object. Example: blockedsite_exception
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
address object	Address of the site to allow or block.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the blocked sites exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.
id string	Unique ID that identifies this exception. Example: bse_12345_EU03pOyqJT1m32k23H
start_after string	If the value of the `more` parameter is true, specifies the ID of the exception to use in another request to retrieve the next page of exceptions. Example: bse_13929_7XsCmfQFvN5uxfrsvY

Version 1 (Deprecated)

/{v1}/configuration/{accountid}/exceptions/blockedsite

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

Request Parameters

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

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

Example Request

This request retrieves all blocked sites and blocked sites exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/blockedsite?query=device:12345 AND action:"allow"  
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes an array that lists all blocked sites and blocked sites exceptions that match the specified query. The response includes only the highest version of each exception.

[
{
"object": "blockedsite_exception",
"description": "Allow 192.0.2.1",
"device": 12345,
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
},
"account": "WGC-1-123abc456",
"author": ""
"created": 1580159344,
"version": 1,
"action": "allow",
"id": "bse_12345_EU03pOyqJT1m32k23H",
},
{
"object": "blockedsite_exception",
"description": "Block example.com",
"device": 12345,
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"account": "WGC-1-123abc456",
"author": ""
"created": 1580160941,
"version": 1,
"action": "block",
"id": "bse_12345_GU56oOcfHD4n56s27O",
}

...					
]

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

blocked_site_exceptions array	List of blocked sites exceptions.
object string	Type of exception object. Example: blockedsite_exception
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
address object	Address of the site to allow or block.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the blocked sites exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.
id string	Unique ID that identifies this exception. Example: bse_12345_EU03pOyqJT1m32k23H

Create Blocked Sites or Blocked Site Exceptions

/{v1}/configuration/{accountid}/exceptions/blockedsite

Make a request to this endpoint to add an address to the Blocked Sites list or Blocked Sites Exceptions list. The value of the action parameter in the blocked sites exception object specifies the list to add the address to. Allow adds the address to the Blocked Sites Exception list. Block adds the address to the Blocked Sites list.

For cloud-managed Fireboxes, the Exceptions page in WatchGuard Cloud shows only blocked sites exception objects that have the Allow action. It does not show objects with the Block action.

Exceptions you configure with the Firebox Management API are saved in your WatchGuard Cloud account. To deploy the saved exceptions to a device, you must make a request to the /v1/commands/{accountid}/deployments endpoint.

Path Parameters

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

accountid
string
REQUIRED

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

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

Request Body

device integer string	Device this exception applies to. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345. For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: 12345, FBCL-12345
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
address object REQUIRED	Address of the site to allow or block.
type string REQUIRED	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string REQUIRED	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Specify a fully qualified domain name, such as example.com or *.example.com. ipv4_host — Specify an IPv4 address, such as 192.0.2.1. ipv4_range — Specify a range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — Specify an IPv4 network. such as 192.0.2.0/24.
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.

Example Request

This request creates a new blocked sites exception for the address 192.0.2.1 for device 12345:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/blockedsite
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"device": 12345,
	"description": "Allow 192.0.2.1",
	"address": 
		{
		"type":"ipv4_host",
		"value": "192.0.2.1"
		},
	"action": "allow"
	}'

Example Response

This response includes the new blocked sites exception object in JSON format:

{
"object": "blockedsite_exception",
"description": "Allow 192.0.2.1",
"device": 12345,
"address": {
		"type": "ipv4_host",
		"value": "192.0.2.1"
},
"id": "bse_12345_EU03pOyqJT1m32k23H",
"author": "",
"created": 1580159344,
"account": "WGC-1-123abc456",
"action": "allow"
"version": 1,
}

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

object string	Type of exception object. Example: blockedsite_exception
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
address object	Address of the site to allow or block.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
id string	Unique ID that identifies this exception. Example: bse_12345_EU03pOyqJT1m32k23H
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the blocked sites exception was created, specified in Unix epoch time format. Example: 1579907960.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.
version integer	Version number of the exception. Example: 1

Retrieve a Blocked Site or Blocked Sites Exception

/{v1}/configuration/{accountid}/exceptions/blockedsite/{objectid}

Make a request to this endpoint to retrieve the specified blocked site or blocked site exception object.

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

objectid
string
REQUIRED

ID of the blocked sites exception to retrieve.

Example: bse_12345_EU03pOyqJT1m32k23H

Example Request

This request retrieves the blocked sites exception with the objectid of bse_12345_EU03pOyqJT1m32k23H:

curl -X GET https://api.dev.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/blockedsite/bse_12345_EU03pOyqJT1m32k23H 	
-H 'Accept: application/json'
-H 'Content-Type: application/json' 
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"object": "blockedsite_exception",
"description": "Allow 192.0.2.1",
"device": 12345,
"address": {
		"type": "ipv4_host",
		"value": "192.0.2.1"
},
"account": "WGC-1-123abc456",
"author": "",
"created": 1580159344,
"version": 1,
"action": "allow",
"id": "bse_12345_EU03pOyqJT1m32k23H"
}

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

object string	Type of exception object. Example: blockedsite_exception
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
address object	Address of the site to allow or block.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
id string	Unique ID that identifies this exception. Example: bse_12345_EU03pOyqJT1m32k23H
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the blocked sites exception was created, specified in Unix epoch time format. Example: 1579907960.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.
version integer	Version number of the exception. Example: 1

Update a Blocked Site or Blocked Sites Exception

/{v1}/configuration/{accountid}/exceptions/blockedsite/{objectid}

Make a request to this endpoint to update the specified blocked site or blocked sites exception with the data in the request body. When you update a blocked site or blocked sites exception, the version number increases by one.

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

objectid
string
REQUIRED

ID of the blocked sites exception to update.

Example: bse_12345_EU03pOyqJT1m32k23H

Request Body

version integer REQUIRED	Version number of the blocked sites exception to update. Example: 1
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
address object REQUIRED	Address of the site to allow or block.
type string REQUIRED	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string REQUIRED	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.

Example Request

This request updates the blocked site with the objectid of bse_12345_EU03pOyqJT1m32k23H:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/blockedsite/bse_12345_EU03pOyqJT1m32k23H 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
		-d '{
		"version": 1,
		"description": "Block example.com",
		"address": 
			{
			"type":"fqdn",
			"value": "example.com"
			},
		"action": "block"
		}'

Example Response

This response includes the updated blocked site object in JSON format:

{
"object": "blockedsite_exception",
"description": "Test Update example.com",
"device": "12124",
"address": {
	"type": "fqdn",
	"value": "example.com"
	},
"account": "WGC-1-123abc456",
"author": "",
"created": 1582597684,
"version": 2,
"action": "block",
"id": "bse_12345_EU03pOyqJT1m32k23H"
}

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

object string	Type of exception object. Example: blockedsite_exception
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
address object	Address of the site to allow or block.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the blocked sites exception was created, specified in Unix epoch time format. Example: 1579907960.
version integer	Version number of the exception. Example: 2
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.
id string	Unique ID that identifies this exception. Example: bse_12345_EU03pOyqJT1m32k23H

Delete a Blocked Site or Blocked Sites Exception

/{v1}/configuration/{accountid}/exceptions/blockedsite/{objectid}

Make a request to this endpoint to delete the specified blocked site or blocked sites exception. When you delete a blocked site or blocked sites exception, the version number increases by one and an inactive parameter with a value of true is added to the object.

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

objectid
string
REQUIRED

ID of the blocked sites exception to delete.

Example: bse_12345_EU03pOyqJT1m32k23H

Example Request

This request deletes the blocked site with the objectid of bse_12345_EU03pOyqJT1m32k23H:

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/blockedsite/bse_12345_EU03pOyqJT1m32k23H 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

This response includes the deleted blocked site object in JSON format:

{
"object": "blockedsite_exception",
"description": "Test Update example.com",
"device": "12124",
"account": "WGC-1-123abc456",
"address": {
			"type": "fqdn",
			"value": "example.com"
			},
"inactive": true,
"author": "",
"created": 1582589612,
"version": 3,
"action": "block",
"id": "bse_12345_EU03pOyqJT1m32k23H"
}

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

object string	Type of exception object. Example: blockedsite_exception
description string	Description of the blocked sites exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site to allow or block.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site to allow or block. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
inactive boolean	Indicates whether the exception is inactive. The value is always true for deleted exceptions. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the blocked sites exception was created, specified in Unix epoch time format. Example: 1579907960.
version integer	Version number of the exception. Example: 1
action string	Action to take for the address. This can be one of these values: allow — Adds the address to the Blocked Sites Exceptions list. The Firebox allows connections to or from addresses on the Blocked Sites Exceptions list. This is the default value. block — Adds the address to the Blocked Sites list. The Firebox denies connections to or from addresses on the Blocked Sites list.
id string	Unique ID that identifies this exception. Example: bse_12345_EU03pOyqJT1m32k23H

Botnet Site Exceptions

Botnet site exceptions specify sites that you do not want to block, even if they are known botnet sites that the Botnet Detection service added to the Blocked Sites list.

For more information about botnet site exceptions, see Botnet Site Exceptions in Fireware Help.

Endpoints:

/{v2}/configuration/{accountid}/exceptions/botnet

/{v1}/configuration/{accountid}/exceptions/botnet

/{v1}/configuration/{accountid}/exceptions/botnet/{objectid}

Query All Botnet Site Exceptions

WatchGuard Cloud stores any botnet site exceptions you create with the Firebox Management API. Make a request to this endpoint to retrieve all botnet site exceptions associated with your WatchGuard Cloud account. If you want to retrieve only specific botnet site exceptions, include the query request parameter.

Version 2

/{v2}/configuration/{accountid}/exceptions/botnet

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

Request Parameters

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

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

Example Request

This request retrieves botnet site exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v2/configuration/WGC-1-123abc456/exceptions/botnet?limit=10&query=device:12345&start_after=bote_12345_8LBasn0hDNXnli4V0 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes an array that lists all botnet site exceptions that match the specified query. The response includes only the highest version of each exception.

{
"count": 10,
"more": true,
"objects":[
{
"object": "botnet_exception",
"description": "Allow 192.0.2.1",
"account": "WGC-1-123abc456",
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
	},
"device": 12345,
"version": 1,
"created": 1582751451,
"author": "",
"id": "bote_12345_8LBasn0hDNXnli4V0"
},
{
"object": "botnet_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"device": 12345,
"version": 1,
"created": 1582751005,
"author": "",
"id": "bote_12345_RbnXwZ9FQMtOXgRPy"
}
					
...
			],
"start_after": "bote_12345_8LBasn0hDNXnli4V0"
}

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

count integer	Number of exceptions returned in the response. Example: 10
more boolean	If the `limit` parameter was specified in the request, this parameter indicates whether more exceptions match the query after the exceptions returned in this response. Example: true
objects array	List of botnet site exceptions.
object string	Type of exception object. Example: botnet_exception
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow example.com.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
version integer	Version number of the exception. Example: 1
created integer	Time that the botnet site exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
id string	Unique ID that identifies this exception. Example: bote_12345_8LBasn0hDNXnli4V0
start_after string	If the value of the `more` parameter is true, specifies the ID of the exception to use in another request to retrieve the next page of exceptions. Example: bote_12345_8LBasn0hDNXnli4V0

Version 1 (Deprecated)

/{v1}/configuration/{accountid}/exceptions/botnet

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

Request Parameters

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

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

Example Request

This request retrieves all botnet site exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/botnet?query=device:12345 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes an array that lists all botnet site exceptions that match the specified query. The response includes only the highest version of each exception.

[
{
"object": "botnet_exception",
"description": "Allow 192.0.2.1",
"account": "WGC-1-123abc456",
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
	},
"device": 12345,
"version": 1,
"created": 1582751451,
"author": "",
"id": "bote_12345_8LBasn0hDNXnli4V0"
},
{
"object": "botnet_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"device": 12345,
"version": 1,
"created": 1582751005,
"author": "",
"id": "bote_12345_RbnXwZ9FQMtOXgRPy"
}
					
...
			]

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

botnet_exceptions array	List of botnet site exceptions.
object string	Type of exception object. Example: botnet_exception
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow example.com.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
version integer	Version number of the exception. Example: 1
created integer	Time that the botnet site exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
id string	Unique ID that identifies this exception. Example: bote_12345_8LBasn0hDNXnli4V0

Create Botnet Site Exceptions

/{v1}/configuration/{accountid}/exceptions/botnet

Make a request to this endpoint to create a new botnet site exception.

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

Request Body

device integer string	Device this exception applies to. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345. For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: 12345, FBCL-12345
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
address object REQUIRED	Address of the site.
type string REQUIRED	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string REQUIRED	Address of the site. This address format must match the address type, as follows: fqdn — Specify a fully qualified domain name, such as example.com or *.example.com. ipv4_host — Specify an IPv4 address, such as 192.0.2.1. ipv4_range — Specify a range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — Specify an IPv4 network. such as 192.0.2.0/24.

Example Request

This request creates a new botnet site exception for the address *.example.com for device 12345:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/botnet
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"device": 12345,
	"description": "Allow example.com",
	"address": 
		{
		"type":"fqdn",
		"value": "*.example.com"
		} 
	}'

Example Response

This response includes the new botnet site exception object in JSON format:

{
"object": "botnet_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"device": 12345,
"version": 1,
"created": 1580497844,
"author": ""
"id": "bote_12345_8LBasn0hDNXnli4V0",
}

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

object string	Type of exception object. Example: botnet_exception
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow example.com.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
version integer	Version number of the exception. Example: 1
created integer	Time that the botnet site exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
id string	Unique ID that identifies this exception. Example: bote_12345_8LBasn0hDNXnli4V0

Retrieve a Botnet Site Exception

/{v1}/configuration/{accountid}/exceptions/botnet/{objectid}

Make a request to this endpoint to retrieve the specified botnet site exception.

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

objectid
string
REQUIRED

ID of the botnet site exception to retrieve.

Example: bote_12345_8LBasn0hDNXnli4V0

Example Request

This request retrieves the botnet site exception with the objectid of bote_12345_8LBasn0hDNXnli4V0:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/botnet/bote_12345_8LBasn0hDNXnli4V0 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"object": "botnet_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"device": 12345,
"version": 1,
"created": 1580497844,
"author": ""
"id": "bote_12345_8LBasn0hDNXnli4V0",
}

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

object string	Type of exception object. Example: botnet_exception
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow example.com.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
version integer	Version number of the exception. Example: 1
created integer	Time that the botnet site exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
id string	Unique ID that identifies this exception. Example: bote_12345_8LBasn0hDNXnli4V0

Update a Botnet Exception

/{v1}/configuration/{accountid}/exceptions/botnet/{objectid}

Make a request to this endpoint to update the specified botnet site exception with the data in the request body. When you update a botnet site exception, the version number increases by one.

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

objectid
string
REQUIRED

ID of the botnet site exception to update.

Example: bote_12345_8LBasn0hDNXnli4V0

Request Body

version integer REQUIRED	Version number of the botnet site exception to update. Example: 1
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Block example.com.
address object REQUIRED	Address of the site.
type string REQUIRED	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string REQUIRED	Address of the site. This address format must match the address type, as follows: fqdn — Specify a fully qualified domain name, such as example.com or *.example.com. ipv4_host — Specify an IPv4 address, such as 192.0.2.1. ipv4_range — Specify a range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — Specify an IPv4 network. such as 192.0.2.0/24.

Example Request

This request updates the botnet site exception with the objectid of bote_12345_8LBasn0hDNXnli4V0:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/botnet/bote_12345_8LBasn0hDNXnli4V0 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
		-d '{
		"version":1,
		"description": "Allow 192.0.2.1",
		"address": 
			{
			"type":"ipv4_host",
			"value": "192.0.2.1"
			}
		}'

Example Response

The response includes the updated botnet site exception object in JSON format:

{
"object": "botnet_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
},
"device": 12345,
"version": 2,
"created": 1580499805,
"author": ""
"id": "bote_12345_8LBasn0hDNXnli4V0",
}

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

object string	Type of exception object. Example: botnet_exception
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow example.com.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
version integer	Version number of the exception. Example: 2
created integer	Time that the botnet site exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
id string	Unique ID that identifies this exception. Example: bote_12345_8LBasn0hDNXnli4V0

Delete a Botnet Site Exception

/{v1}/configuration/{accountid}/exceptions/botnet/{objectid}

Make a request to this endpoint to delete the specified botnet site exception. When you delete a botnet site exception, the version number increases by one and an inactive parameter with a value of true is added to the object.

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

objectid
string
REQUIRED

ID of the botnet site exception to delete.

Example: bote_12345_8LBasn0hDNXnli4V0

Example Request

This request deletes the botnet site exception with the objectid of bote_12345_8LBasn0hDNXnli4V0:

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/botnet/bote_12345_8LBasn0hDNXnli4V0 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
		-d '{
			"version":1,
			"description": "Allow 192.0.2.1",
			"address": 
			{
			"type":"ipv4_host",
			"value": "192.0.2.1"
			}
		}'

Example Response

The response includes the deleted botnet site exception in JSON format:

{
"object": "botnet_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
},
"device": 12345,
"version": 3,
"inactive": true,
"created": 1580499805,
"author": ""
"id": "bote_12345_8LBasn0hDNXnli4V0",
}

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

object string	Type of exception object. Example: botnet_exception
description string	Description of the botnet site exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow example.com.
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
version integer	Version number of the exception. Example: 3
inactive boolean	Indicates whether the exception is inactive. The value is always true for deleted exceptions. Example: true
created integer	Time that the botnet site exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
id string	Unique ID that identifies this exception. Example: bote_12345_8LBasn0hDNXnli4V0

File Exceptions

The File Exceptions list includes files that you do not want to scan with these security services:

APT Blocker
Data Loss Prevention
Gateway AntiVirus
IntelligentAV

When the Firebox examines a file, it checks the MD5 hash of the file against any file exceptions. If the file matches a file exception, the Firebox skips the relevant scans and either allows or drops the file, based on the specified action.

For more information about file exceptions, see Configure File Exceptions in Fireware Help.

Endpoints:

/{v2}/configuration/{accountid}/exceptions/file

/{v1}/configuration/{accountid}/exceptions/file

/{v1}/configuration/{accountid}/exceptions/file/{objectid}

Query All File Exceptions

WatchGuard Cloud stores any file exceptions you create with the Firebox Management API. Make a request to this endpoint to retrieve all file exceptions associated with your WatchGuard Cloud account. If you want to retrieve only specific file exceptions, include the query request parameter.

Version 2

/{v2}/configuration/{accountid}/exceptions/file

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

Request Parameters

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

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

Example Request

This request retrieves file exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/file?limit=10&query=device:12345&start_after=file_12345_UqhDVIdx8D5iwivAX 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"count": 10,
"more": true,
"objects":[
{
"object": "file_exception",
"description": "Drop malicious exe",
"account": "WGC-1-123abc456",
"md5": "36f72eb9f68337c44c86be68968ce83c",
"version": 1,
"device": 12345,
"created": 1582755960,
"author": "",
"action": "drop",
"id": "file_12345_UqhDVIdx8D5iwivAX"
},
{
"object": "file_exception",
"description": "Allow Sales Brochure PDF",
"account": "WGC-1-123abc456",
"md5": "d6f19bb6d8b48419c2a7f752dfaba81e",
"version": 1,
"device": 12345,
"created": 1582760851,
"author": "",
"action": "allow",
"id": "file_12345_n4AeGRHpqPuPGZeu2"
}

...
],
"start_after": "file_12345_UqhDVIdx8D5iwivAX"
}

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

count integer	Number of exceptions returned in the response. Example: 10
more boolean	If the `limit` parameter was specified in the request, this parameter indicates whether more exceptions match the query after the exceptions returned in this response. Example: true
objects array	List of file exceptions.
object string	Type of exception object. Example: file_exception
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
md5 string	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c
version integer	Version number of the exception. Example: 1
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
id string	Unique ID that identifies this exception. Example: file_12345_n4AeGRHpqPuPGZeu2
start_after string	If the value of the `more` parameter is true, specifies the ID of the exception to use in another request to retrieve the next page of exceptions. Example: file_12345_n4AeGRHpqPuPGZeu2

Version 1 (Deprecated)

/{v1}/configuration/{accountid}/exceptions/file

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

Request Parameters

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

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

Example Request

This request retrieves all file exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/file?query=device:12345 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

[
{
"object": "file_exception",
"description": "Drop malicious exe",
"account": "WGC-1-123abc456",
"md5": "36f72eb9f68337c44c86be68968ce83c",
"version": 1,
"device": 12345,
"created": 1582755960,
"author": "",
"action": "drop",
"id": "file_12345_UqhDVIdx8D5iwivAX"
},
{
"object": "file_exception",
"description": "Allow Sales Brochure PDF",
"account": "WGC-1-123abc456",
"md5": "d6f19bb6d8b48419c2a7f752dfaba81e",
"version": 1,
"device": 12345,
"created": 1582760851,
"author": "",
"action": "allow",
"id": "file_12345_n4AeGRHpqPuPGZeu2"
}

...
]

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

file_exceptions array	List of file exceptions.
object string	Type of exception object. Example: file_exception
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
md5 string	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c
version integer	Version number of the exception. Example: 1
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
id string	Unique ID that identifies this exception. Example: file_12345_n4AeGRHpqPuPGZeu2

Create File Exceptions

/{v1}/configuration/{accountid}/exceptions/file

Make a request to this endpoint to create a new file exception from the data in the request body.

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

Request Body

device integer string	Device this exception applies to. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345. For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: 12345, FBCL-12345
action string REQUIRED	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
md5 string REQUIRED	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c

Example Request

This request creates a new file exception for the file with an MD5 hash of 36f72eb9f68337c44c86be68968ce83c for device 12345:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/file 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"device": 12345,
	"description": "Drop malicious executable",
	"md5":"36f72eb9f68337c44c86be68968ce83c", 
	"action": "drop"
	}'

Example Response

The response includes the new file exception object in JSON format:

{
"object": "file_exception",
"description": "Drop malicious executable",
"account": "WGC-1-123abc456",
"md5": "36f72eb9f68337c44c86be68968ce83c",
"device": 12345,
"author": "",
"created": 1582853506,
"version": 1,
"action": "drop",
"id": "file_12345_n4AeGRHpqPuPGZeu2"
}

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

object string	Type of exception object. Example: file_exception
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
md5 string	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
id string	Unique ID that identifies this exception. Example: file_12345_n4AeGRHpqPuPGZeu2

Retrieve a File Exception

/{v1}/configuration/{accountid}/exceptions/file/{objectid}

Make a request to this endpoint to retrieve the specified file exception.

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

objectid
string
REQUIRED

ID of the file exception to retrieve.

Example: file_12345_n4AeGRHpqPuPGZeu2

Example Request

This request retrieves the file exception with the objectid of file_12345_n4AeGRHpqPuPGZeu2:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/file/file_12345_n4AeGRHpqPuPGZeu2 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"object": "file_exception",
"description": "Drop malicious executable",
"account": "WGC-1-123abc456",
"md5": "36f72eb9f68337c44c86be68968ce83c",
"device": 12345,
"author": "",
"created": 1582853506,
"version": 1,
"action": "drop",
"id": "file_12345_n4AeGRHpqPuPGZeu2"
}

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

object string	Type of exception object. Example: file_exception
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
md5 string	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
id string	Unique ID that identifies this exception. Example: file_12345_n4AeGRHpqPuPGZeu2

Update a File Exception

/{v1}/configuration/{accountid}/exceptions/file/{objectid}

Make a request to this endpoint to update the specified file exception with the data in the request body. When you update a file exception, the version number increases by one.

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

objectid
string
REQUIRED

ID of the file exception to update.

Example: file_12345_n4AeGRHpqPuPGZeu2

Request Body

version integer REQUIRED	Version number of the file exception to update. Example: 1
action string REQUIRED	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
md5 string REQUIRED	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c

Example Request

This request updates the file exception with the objectid of file_12345_n4AeGRHpqPuPGZeu2:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/file/file_12345_n4AeGRHpqPuPGZeu2 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"version": 1,
	"action": "drop",
	"md5":"e4f23ef7e9a342aed1f654ea12bad32e", 
	"description": "Drop malicious executable"
	}'

Example Response

The response includes the updated file exception object in JSON format:

{
"object": "file_exception",
"description": "Drop malicious executable",
"account": "WGC-1-123abc456",
"md5": "e4f23ef7e9a342aed1f654ea12bad32e",
"device": 12345,
"author": "",
"created": 1582854721,
"version": 2,
"action": "drop",
"id": "file_12345_n4AeGRHpqPuPGZeu2"
}

object string	Type of exception object. Example: file_exception
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
md5 string	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
id string	Unique ID that identifies this exception. Example: file_12345_n4AeGRHpqPuPGZeu2

Delete a File Exception

/{v1}/configuration/{accountid}/exceptions/file/{objectid}

Make a request to this endpoint to delete the specified file exception. When you delete a file exception, the version number increases by one and an inactive parameter with a value of true is added to the object.

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

objectid
string
REQUIRED

ID of the file exception to retrieve.

Example: file_GsBoJcK2cY5UDI4PSEq0UPM

Example Request

This request deletes the file exception with the objectid of file_12345_n4AeGRHpqPuPGZeu2.

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/file/file_12345_n4AeGRHpqPuPGZeu2 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes the deleted file exception object in JSON format:

{
"object": "file_exception",
"description": "Drop malicious executable",
"account": "WGC-1-123abc456",
"md5": "e4f23ef7e9a342aed1f654ea12bad32e",
"device": 12345,
"inactive": true,
"author": "",
"created": 1582859124,
"version": 3,
"action": "drop",
"id": "file_12345_n4AeGRHpqPuPGZeu2"
}

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

object string	Type of exception object. Example: file_exception
description string	Description of the file exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Drop malicious executable
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
md5 string	MD5 hash of the file. Must be 32 characters (lowercase letters a-f and numbers only). Example: 36f72eb9f68337c44c86be68968ce83c
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
inactive boolean	Indicates whether the exception is inactive. The value is always true for deleted exceptions. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the file. This can be one of these values: allow — Allows the file to download or delivers the email attachment to the recipient. Use this action for files that you always want to allow. For example, you could allow a file that triggers a false positive when scanned by IntelligentAV. drop — Denies the transaction (HTTP), drops the connection (FTP), or removes the attachment from the email before it is delivered to the recipient (SMTP/POP3/IMAP). Use this action for files that you always want to reject. For example, you could immediately drop files that are known to contain malware.
id string	Unique ID that identifies this exception. Example: file_12345_n4AeGRHpqPuPGZeu2

Geolocation Exceptions

To identify the geographic location of connections through the Firebox, the Geolocation subscription service uses a database of IP addresses and countries. You can add Geolocation exceptions for sites that you never want to block based on information in the Geolocation database. Geolocation never blocks connections to or from sites on the exceptions list.

For more information about Geolocation exceptions, see Configure Geolocation Exceptions in Fireware Help.

Endpoints:

/{v2}/configuration/{accountid}/exceptions/geolocation

/{v1}/configuration/{accountid}/exceptions/geolocation

/{v1}/configuration/{accountid}/exceptions/geolocation/{objectid}

Query All Geolocation Exceptions

WatchGuard Cloud stores any Geolocation exceptions you create with the Firebox Management API. Make a request to this endpoint to retrieve all Geolocation exceptions associated with your WatchGuard Cloud account. If you want to retrieve only specific Geolocation exceptions, include the query request parameter.

Version 2

/{v2}/configuration/{accountid}/exceptions/geolocation

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

Request Parameters

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

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

Example Request

This request retrieves Geolocation exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v2/configuration/WGC-1-123abc456/exceptions/geolocation?limit=10&query=device:12345&start_after=geoe_12345_aHbWC5IuWO3qzyV2t 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"count": 10,
"more": true,
"objects":[
{
"object": "geolocation_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "www.example.com"
	},
"device": 12345,
"author": "",
"created": 1582756088,
"version": 1,
"id": "geoe_12345_aHbWC5IuWO3qzyV2t"
},
{
"object": "geolocation_exception",
"description": "Allow 192.0.2.1",
"account": "WGC-1-123abc456",
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
	},
"device": 12345,
"author": "",
"created": 1583005651,
"version": 1,
"id": "geoe_12345_pkPGFCRqE8DRFf6kz"
}

...
],
"start_after": "geoe_12345_aHbWC5IuWO3qzyV2t"
}

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

count integer	Number of exceptions returned in the response. Example: 10
more boolean	If the `limit` parameter was specified in the request, this parameter indicates whether more exceptions match the query after the exceptions returned in this response. Example: true
objects array	List of Geolocation exceptions.
object string	Type of exception object. Example: geolocation_exception
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
id string	Unique ID that identifies this exception. Example: geoe_12345_pkPGFCRqE8DRFf6kz
start_after string	If the value of the `more` parameter is true, specifies the ID of the exception to use in another request to retrieve the next page of exceptions. Example: geoe_12345_pkPGFCRqE8DRFf6kz

Version 1 (Deprecated)

/{v1}/configuration/{accountid}/exceptions/geolocation

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

Request Parameters

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

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

Example Request

This request retrieves all Geolocation exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/geolocation?query=device:12345 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

[
{
"object": "geolocation_exception",
"description": "Allow example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "www.example.com"
	},
"device": 12345,
"author": "",
"created": 1582756088,
"version": 1,
"id": "geoe_12345_aHbWC5IuWO3qzyV2t"
},
{
"object": "geolocation_exception",
"description": "Allow 192.0.2.1",
"account": "WGC-1-123abc456",
"address": {
	"type": "ipv4_host",
	"value": "192.0.2.1"
	},
"device": 12345,
"author": "",
"created": 1583005651,
"version": 1,
"id": "geoe_12345_pkPGFCRqE8DRFf6kz"
}

...
]

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

geolocation_exceptions array	List of Geolocation exceptions.
object string	Type of exception object. Example: geolocation_exception
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the file exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
id string	Unique ID that identifies this exception. Example: geoe_12345_pkPGFCRqE8DRFf6kz

Create Geolocation Exceptions

/{v1}/configuration/{accountid}/exceptions/geolocation

Make a request to this endpoint to create a new Geolocation exception from the data in the request body.

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

Request Body

device integer string	Device this exception applies to. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345. For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: 12345, FBCL-12345
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
address object REQUIRED	Address of the site.
type string REQUIRED	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string REQUIRED	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.

Example Request

This request creates a new Geolocation exception for the site www.example.com for device 12345:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/geolocation 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"device": 12345,
	"description": "Allow www.example.com",
	"address": 
	{
	"type": "fqdn",
	"value": "www.example.com"	
	}
}'

Example Response

The response includes a new Geolocation object in JSON format:

{
"object": "geolocation_exception",
"description": "Allow www.example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "www.example.com"
},
"device": 12345,
"author": "",
"created": 1583007222,
"version": 1,
"id": "geoe_12345_pkPGFCRqE8DRFf6kz"
}

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

object string	Type of exception object. Example: geolocation_exception
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the Geolocation exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
id string	Unique ID that identifies this exception. Example: geoe_12345_pkPGFCRqE8DRFf6kz

Retrieve a Geolocation Exception

/{v1}/configuration/{accountid}/exceptions/geolocation/{objectid}

Make a request to this endpoint to retrieve the specified Geolocation exception.

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

objectid
string
REQUIRED

ID of the Geolocation exception to retrieve.

Example: geoe_12345_pkPGFCRqE8DRFf6kz

Example Request

This request retrieves the Geolocation exception with the objectid of geoe_12345_pkPGFCRqE8DRFf6kz:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/geolocation/geoe_12345_pkPGFCRqE8DRFf6kz 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"object": "geolocation_exception",
"description": "Allow www.example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "www.example.com"
},
"device": 12345,
"author": "",
"created": 1583007222,
"version": 1,
"id": "geoe_12345_pkPGFCRqE8DRFf6kz"
}

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

object string	Type of exception object. Example: geolocation_exception
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the Geolocation exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
id string	Unique ID that identifies this exception. Example: geoe_12345_pkPGFCRqE8DRFf6kz

Update a Geolocation Exception

/{v1}/configuration/{accountid}/exceptions/geolocation/{objectid}

Make a request to this endpoint to update the specified Geolocation exception with the data in the request body. When you update a Geolocation exception, the version number increases by one.

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

objectid
string
REQUIRED

ID of the Geolocation exception to update.

Example: geoe_12345_pkPGFCRqE8DRFf6kz

Request Body

version integer REQUIRED	Version number of the Geolocation exception to update. Example: 1
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
address object REQUIRED	Address of the site.
type string REQUIRED	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string REQUIRED	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.

Example Request

This request updates the Geolocation exception with the objectid of geoe_12345_pkPGFCRqE8DRFf6kz:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/geolocation/geoe_12345_pkPGFCRqE8DRFf6kz 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"version": 1,
	"description": "Allow *.example.com",
	"address": 
		{
		"type": "fqdn",
		"value": "*.example.com"	
		},
	}'

Example Response

The response includes the updated Geolocation exception object in JSON format:

{
"object": "geolocation_exception",
"description": "Allow *.example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"device": 12345,
"author": "",
"created": 1583008145,
"version": 2,
"id": "geoe_12345_pkPGFCRqE8DRFf6kz"
}

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

object string	Type of exception object. Example: geolocation_exception
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the Geolocation exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
id string	Unique ID that identifies this exception. Example: geoe_12345_pkPGFCRqE8DRFf6kz

Delete a Geolocation Exception

/{v1}/configuration/{accountid}/exceptions/geolocation/{objectid}

Make a request to this endpoint to delete the specified Geolocation exception. When you delete a Geolocation exception, the version number increases by one and an inactive parameter with a value of true is added to the object.

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

objectid
string
REQUIRED

ID of the Geolocation exception to delete.

Example: geoe_12345_pkPGFCRqE8DRFf6kz

Example Request

This request deletes the Geolocation exception with the objectid of geoe_12345_pkPGFCRqE8DRFf6kz:

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/geolocation/geoe_12345_pkPGFCRqE8DRFf6kz 
-H 'Accept: application/json'
-H 'Content-Type: application/json' 
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes the deleted Geolocation exception in JSON format:

{
"object": "geolocation_exception",
"description": "Allow *.example.com",
"account": "WGC-1-123abc456",
"address": {
	"type": "fqdn",
	"value": "*.example.com"
},
"device": 12345,
"inactive": true,
"author": "",
"created": 1583008145,
"version": 2,
"id": "geoe_12345_pkPGFCRqE8DRFf6kz"
}

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

object string	Type of exception object. Example: geolocation_exception
description string	Description of the Geolocation exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 192.0.2.1
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
address object	Address of the site.
type string	Type of address. This can be one of these values: fqdn — A fully qualified domain name. ipv4_host — An IPv4 address. ipv4_range — An IPv4 address range. ipv4_network — An IPv4 network.
value string	Address of the site. This address format must match the address type, as follows: fqdn — Fully qualified domain name, such as example.com or *.example.com. ipv4_host — IPv4 address, such as 192.0.2.1. ipv4_range — Range of IPv4 addresses (two addresses separated by a hyphen), such as 192.0.2.1-192.0.2.5. ipv4_network — IPv4 network. such as 192.0.2.0/24.
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
inactive boolean	Indicates whether the exception is inactive. The value is always `true` for deleted exceptions. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the Geolocation exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
id string	Unique ID that identifies this exception. Example: geoe_12345_pkPGFCRqE8DRFf6kz

Intrusion Prevention Service (IPS) Exceptions

The Intrusion Prevention Service (IPS) uses signatures to provide real-time protection against network attacks. To allow traffic that IPS blocks, you can find the identification number for the IPS signature (the signature ID) and add an IPS exception for the signature ID.

For more information about IPS exceptions, see Configure IPS Exceptions in the Fireware Help.

Endpoints:

/{v2}/configuration/{accountid}/exceptions/ips

/{v1}/configuration/{accountid}/exceptions/ips

/{v1}/configuration/{accountid}/exceptions/ips/{objectid}

Query All Intrusion Prevention Service Exceptions

WatchGuard Cloud stores any Intrusion Prevention Service (IPS) exceptions you create with the Firebox Management API. Make a request to this endpoint to retrieve all IPS exceptions associated with your WatchGuard Cloud account. If you want to retrieve only specific IPS exceptions, include the query request parameter.

Version 2

/{v2}/configuration/{accountid}/exceptions/ips

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

Request Parameters

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

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

Example Request

This request retrieves IPS exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v2/configuration/WGC-1-123abc456/exceptions/ips?limit=10&query=device:12345&start_after=ipse_12345_eY5Jwxv1nE3Xlk3zx 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"count": 10,
"more": true,
"objects":[
{
"object": "ips_exception",
"signature_id": "1234567890123456789013245679801",
"account": "WGC-1-123abc456",
"description": "Allow 523456789",
"device": 12345,
"alarm": false,
"author": "",
"created": 1582756189,
"version": 1,
"action": "allow",
"id": "ipse_12345_3rZNNiSxEO0u7ILhx"
},
{
"object": "ips_exception",
"signature_id": "5234567890123456789013245679801",
"account": "WGC-1-123abc456",
"description": "Allow 523456789",
"device": 12345,
"alarm": false,
"author": "",
"created": 1582412997,
"version": 1,
"action": "allow",
"id": "ipse_12345_ifxDmHNujdFheV2dE"
}

...
],
"start_after": "ipse_12345_eY5Jwxv1nE3Xlk3zx"
}

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

count integer	Number of exceptions returned in the response. Example: 10
more boolean	If the `limit` parameter was specified in the request, this parameter indicates whether more exceptions match the query after the exceptions returned in this response. Example: true
objects array	List of IPS exceptions.
object string	Type of exception object. Example: ips_exception
signature_id string	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. The Firebox sends no information to the source of the content.
id string	Unique ID that identifies this exception. Example: ipse_12124_G4dywojda1rjAv95J
start_after string	If the value of the `more` parameter is true, specifies the ID of the exception to use in another request to retrieve the next page of exceptions. Example: ipse_12345_eY5Jwxv1nE3Xlk3zx

Version 1 (Deprecated)

/{v1}/configuration/{accountid}/exceptions/ips

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

Request Parameters

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

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

Example Request

This request retrieves all IPS exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/ips?query=device:12345 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

[
{
"object": "ips_exception",
"signature_id": "1234567890123456789013245679801",
"account": "WGC-1-123abc456",
"description": "Allow 523456789",
"device": 12345,
"alarm": false,
"author": "",
"created": 1582756189,
"version": 1,
"action": "allow",
"id": "ipse_12345_3rZNNiSxEO0u7ILhx"
},
{
"object": "ips_exception",
"signature_id": "5234567890123456789013245679801",
"account": "WGC-1-123abc456",
"description": "Allow 523456789",
"device": 12345,
"alarm": false,
"author": "",
"created": 1582412997,
"version": 1,
"action": "allow",
"id": "ipse_12345_ifxDmHNujdFheV2dE"
}

...
]

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

ips_exceptions array	List of IPS exceptions.
object string	Type of exception object. Example: ips_exception
signature_id string	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. The Firebox sends no information to the source of the content.
id string	Unique ID that identifies this exception. Example: ipse_12124_G4dywojda1rjAv95J

Create Intrusion Prevention Service Exceptions

/{v1}/configuration/{accountid}/exceptions/ips

Make a request to this endpoint to create a new IPS exception.

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

Request Body

device integer string	Device this exception applies to. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345. For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: 12345, FBCL-12345
action string REQUIRED	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. The Firebox sends no information to the source of the content.
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. The default value is false. Example: true
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
signature_id string REQUIRED	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345

Example Request

This request creates a new IPS exception for the signature 123456789012345:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/ips 
	-H 'Accept: application/json' 
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"device": 12345,
	"action": "allow",
	"alarm": true,
	"description": "Allow 123456789012345",
	"signature_id": "123456789012345" 
	}'

Example Response

{
"object": "ips_exception",
"signature_id": "123456789012345",
"account": "WGC-1-123abc456",
"description": "Allow 123456789012345",
"device": 12345,
"alarm": true,
"author": "",
"created": 1582412997,
"version": 1,
"action": "allow",
"id": "ipse_12345_ifxDmHNujdFheV2dE"
}

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

object string	Type of exception object. Example: ips_exception
signature_id string	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. The default value is false. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. The Firebox sends no information to the source of the content.
id string	Unique ID that identifies this exception. Example: ipse_12345_ifxDmHNujdFheV2dE

Retrieve an Intrusion Prevention Service (IPS) Exception

/{v1}/configuration/{accountid}/exceptions/ips/{objectid}

Make a request to this endpoint to retrieve the specified IPS exception.

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

objectid
string
REQUIRED

ID of the IPS exception to retrieve.

Example: ipse_12345_ifxDmHNujdFheV2dE

Example Request

This request retrieves the IPS exception with the objectid of ipse_12345_ifxDmHNujdFheV2dE:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/ips/ipse_12345_ifxDmHNujdFheV2dE 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"object": "ips_exception",
"signature_id": "123456789012345",
"account": "WGC-1-123abc456",
"description": "Allow 123456789012345",
"device": 12345,
"alarm": true,
"author": "",
"created": 1582412997,
"version": 1,
"action": "allow",
"id": "ipse_12345_ifxDmHNujdFheV2dE"
}

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

object string	Type of exception object. Example: ips_exception
signature_id string	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. The default value is false. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. No information is sent to the source of the content.
id string	Unique ID that identifies this exception. Example: ipse_12345_ifxDmHNujdFheV2dE

Update an Intrusion Prevention Service (IPS) Exception

/{v1}/configuration/{accountid}/exceptions/ips/{objectid}

Make a request to this endpoint to update the specified IPS exception with the data in the request body. When you update a IPS, the version number increases by one.

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

objectid
string
REQUIRED

ID of the IPS exception to update.

Example: ipse_12345_ifxDmHNujdFheV2dE

Request Body

version integer REQUIRED	Version number of the IPS exception to update. Example: 1
action string REQUIRED	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. No information is sent to the source of the content.
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. The default value is false. Example: true
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
signature_id string REQUIRED	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345

Example Request

This request updates the IPS exception with the objectid of ipse_12345_ifxDmHNujdFheV2dE:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/ips/ipse_12345_ifxDmHNujdFheV2dE 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"version": 1,
	"action": "drop",
	"alarm": true,
	"description": "Drop 123456789012345",
	"signature_id": "123456789012345" 
	}'

Example Response

The response includes the updated IPS exception in JSON format:

{
"object": "ips_exception",
"signature_id": "123456789012345",
"account": "WGC-1-123abc456",
"description": "Drop 123456789012345",
"device": 12345,
"alarm": true,
"author": "",
"created": 1582412997,
"version": 2,
"action": "drop",
"id": "ipse_12345_ifxDmHNujdFheV2dE"
}

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

object string	Type of exception object. Example: ips_exception
signature_id string	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. The default value is false. Example: true
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
version integer	Version number of the exception. Example: 1
action string	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. No information is sent to the source of the content.
id string	Unique ID that identifies this exception. Example: ipse_12345_ifxDmHNujdFheV2dE

Delete an Intrusion Prevention Service (IPS) Exception

/{v1}/configuration/{accountid}/exceptions/ips/{objectid}

Make a request to this endpoint to delete the specified IPS exception. When you delete an IPS exception, the version number increases by one and an inactive parameter with a value of true is added to the object.

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

objectid
string
REQUIRED

ID of the IPS signature exception to delete.

Example: ipse_12345_ifxDmHNujdFheV2dE

Example Request

This request deletes the IPS exception with an objectid of pse_12345_ifxDmHNujdFheV2dE:

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/ips/ipse_12345_ifxDmHNujdFheV2dE 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes the deleted IPS exception in JSON format:

{
"object": "ips_exception",
"description": "Drop 123456789012345",
"account": "WGC-1-123abc456",
"inactive":true,
"device": 12345,
"version": 3,
"signature_id": "123456789012345",
"alarm": true,
"id": "ipse_12345_ifxDmHNujdFheV2dE"
"created": 1582412997,
"author": "",
"action": "drop"
}

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

object string	Type of exception object. Example: ips_exception
description string	Description of the IPS exception. Letters, numbers, spaces, commas, and (-_+.*:@/;) only. Maximum: 127 characters. Example: Allow 123456789012345
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
inactive boolean	Indicates whether the exception is inactive. The value is always true for deleted exceptions. Example: true
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
version integer	Version number of the exception. Example: 1
signature_id string	IPS signature ID. Must contain only numbers. Maximum: 31 characters. You can see IPS signature IDs in Fireware Web UI or Firebox System Manager. For more information, see Show IPS Signature Information in Fireware Help. You can also look up signature IDs on the WatchGuard Security Portal. Example: 123456789012345
alarm boolean	Specifies whether the Firebox sends an alarm for the IPS exception. The default value is false. Example: true
id string	Unique ID that identifies this exception. Example: ipse_12345_ifxDmHNujdFheV2dE
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the specified signature. This can be one of these values: allow — Allows the connection. block — Denies the request, drops the connection, and adds the IP address of the content source to the Blocked Sites list. drop — Denies the request and drops the connection. No information is sent to the source of the content.

WebBlocker Exceptions

WebBlocker might deny connections to a website that is necessary for your business, based on the website category in the WebBlocker URL categorization database. To configure WebBlocker to always allow or deny access to a site, regardless of the site category, you can define a WebBlocker exception.

For more information about WebBlocker exceptions, see About WebBlocker Exceptions in Fireware Help.

Endpoints:

/{v2}/configuration/{accountid}/exceptions/webblocker

/{v1}/configuration/{accountid}/exceptions/webblocker

/{v1}/configuration/{accountid}/exceptions/webblocker/{objectid}

Query All WebBlocker Exceptions

WatchGuard Cloud stores any WebBlocker exceptions you create with the Firebox Management API. Make a request to this endpoint to retrieve all WebBlocker exceptions associated with your WatchGuard Cloud account. If you want to retrieve only specific WebBlocker exceptions, include the query request parameter.

Version 2

/{v2}/configuration/{accountid}/exceptions/webblocker

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

Request Parameters

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

limit
integer

Specifies the maximum number of objects to return in the response.

Example: 10

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

start_after
string

Specifies the ID of the first exception to return in the response.

Example: wbe_12124_7HM70EvrifZ7rSfXSA

Example Request

This request retrieves WebBlocker exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v2/configuration/WGC-1-123abc456/exceptions/webblocker?limit=10&query=device:12345&start_after=wbe_12124_7HM70EvrifZ7rSfXSA 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"count": 10,
"more": true,
"objects":[
{
"object": "webblocker_exception",
"name": "Deny example.com",
"created": 1582756302,
"device": 12345,
"rule_type": "string",
"version": 1,
"alarm": false,
"account": "WGC-1-123abc456",
"id": "wbe_12345_7HM70EvrifZ7rSfXSA",
"rule": "www.example.com",
"author": "",
"action": "deny"
},
{
"object": "webblocker_exception",
"name": "Allow watchguard.com",
"created": 1583019217,
"device": 12345,
"rule_type": "pattern",
"version": 1,
"alarm": false,
"account": "WGC-1-123abc456",
"id": "wbe_12345_HttDu2WDTmZg2xaQm6",
"rule": "wwww.watchguard.com/*",
"author": "",
"action": "allow"
}
				
...				
],
"start_after": "bse_12345_ARBHLJ70Y78rGOIGBS"
}

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

count integer	Number of exceptions returned in the response. Example: 10
more boolean	If the `limit` parameter was specified in the request, this parameter indicates whether more exceptions match the query after the exceptions returned in this response. Example: true
objects array	List of WebBlocker exceptions.
object string	Type of exception object. Example: webblocker_exception
name string	Name of the WebBlocker exception. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: Allow example.com
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
rule-type string	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, `\.[onc][eor][gtm]` matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
version integer	Version number of the exception. Example: 1
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
id string	Unique ID that identifies this exception. Example: wbe_12124_7HM70EvrifZ7rSfXSA
rule string	The URL pattern, value, or expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net] Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.
start_after string	If the value of the `more` parameter is true, specifies the ID of the exception to use in another request to retrieve the next page of exceptions. Example: wbe_12124_7HM70EvrifZ7rSfXSA

Version 1 (Deprecated)

/{v1}/configuration/{accountid}/exceptions/webblocker

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

Request Parameters

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

query
string

Query string that specifies which exceptions to retrieve from WatchGuard Cloud, written in Lucene query syntax.

Specify parameter names and associated values to retrieve exceptions that match those values.

For example, the query string object:"botnet_exception" retrieves exceptions that have botnet_exception as the value for the object parameter.

Examples:

object:"botnet_exception" AND address.value:"www.example.com"

object:"blockedsite_exception" AND value:"allow"

"device:12345" OR "device:FBCL-23456"

For more information on how to construct query strings, see the Apache Lucene documentation.

Example Request

This request retrieves all WebBlocker exceptions for device 12345 from the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/webblocker?query=device:12345 
		-H 'Accept: application/json'
		-H 'Content-Type: application/json' 
		-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
		-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

[
{
"object": "webblocker_exception",
"name": "Deny example.com",
"created": 1582756302,
"device": 12345,
"rule_type": "string",
"version": 1,
"alarm": false,
"account": "WGC-1-123abc456",
"id": "wbe_12345_7HM70EvrifZ7rSfXSA",
"rule": "www.example.com",
"author": "",
"action": "deny"
},
{
"object": "webblocker_exception",
"name": "Allow watchguard.com",
"created": 1583019217,
"device": 12345,
"rule_type": "pattern",
"version": 1,
"alarm": false,
"account": "WGC-1-123abc456",
"id": "wbe_12345_HttDu2WDTmZg2xaQm6",
"rule": "wwww.watchguard.com/*",
"author": "",
"action": "allow"
}
				
...				
]

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

webblocker_exceptions array	List of WebBlocker exceptions.
object string	Type of exception object. Example: webblocker_exception
name string	Name of the WebBlocker exception. Maximum: 58 characters. Example: Allow example.com
created integer	Time that the IPS exception was created, specified in Unix epoch time format. Example: 1579907960
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
rule-type string	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, `\.[onc][eor][gtm]` matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
version integer	Version number of the exception. Example: 1
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
id string	Unique ID that identifies this exception. Example: ipse_12124_G4dywojda1rjAv95J
rule string	The URL pattern, value, or expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net] Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.

Create WebBlocker Exceptions

/{v1}/configuration/{accountid}/exceptions/webblocker

Make a request to this endpoint to create a new WebBlocker exception.

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

Request Body

device integer string	Device this exception applies to. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is FB-12345. For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: 12345, FBCL-12345
action string REQUIRED	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
name string REQUIRED	Name of the WebBlocker exception. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: Allow example.com
rule-type string REQUIRED	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, \.[onc][eor][gtm] matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
rule string REQUIRED	The URL pattern, value, or regular expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net] Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.

Example Request

This request adds a new WebBlocker exception to allow requests to all URL paths on www.watchguard.com:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/webblocker 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"device": 12345,
	"action": "allow",
	"alarm": true,
	"name": "Allow watchguard.com",
	"rule_type": "pattern",
	"rule": "www.watchguard.com/*"
	}'

Example Response

The response includes the new WebBlocker exception object in JSON format:

{
"object": "webblocker_exception",
"name": "Allow watchguard.com",
"created": 1583019217,
"device": 12345,
"rule_type": "pattern",
"version": 1,
"alarm": true,
"account": "WGC-1-123abc456",
"id": "wbe_12345_HttDu2WDTmZg2xaQm6",
"rule": "wwww.watchguard.com/*",
"author": "",
"action": "allow"
}

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

object string	Type of exception object. Example: webblocker_exception
name string	Name of the WebBlocker exception. This can include include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: Allow example.com
created integer	Time that the WebBlocker exception was created, specified in Unix epoch time format. Example: 1579907960
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
rule-type string	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, \.[onc][eor][gtm] matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
version integer	Version number of the exception. Example: 1
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
id string	Unique ID that identifies this exception. Example: wbe_12345_HttDu2WDTmZg2xaQm6
rule string	The URL pattern, value, or expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net] Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.

Retrieve a WebBlocker Exception

/{v1}/configuration/{accountid}/exceptions/webblocker/{objectid}

Make a request to this endpoint to retrieve the specified WebBlocker exception.

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

objectid
string
REQUIRED

ID of the WebBlocker exception to retrieve.

Example: wbe_12345_HttDu2WDTmZg2xaQm6

Example Request

This request retrieves the WebBlocker exception with the objectid of wbe_12345_HttDu2WDTmZg2xaQm6:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/webblocker/wbe_12345_HttDu2WDTmZg2xaQm6 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

{
"object": "webblocker_exception",
"name": "Allow watchguard.com",
"created": 1583019217,
"device": 12345,
"rule_type": "pattern",
"version": 1,
"alarm": true,
"account": "WGC-1-123abc456",
"id": "wbe_12345_HttDu2WDTmZg2xaQm6",
"rule": "wwww.watchguard.com/*",
"author": "",
"action": "allow"
}

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

object string	Type of exception object. Example: webblocker_exception
name string	Name of the WebBlocker exception. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: Allow example.com
created integer	Time that the WebBlocker exception was created, specified in Unix epoch time format. Example: 1579907960
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
rule-type string	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, \.[onc][eor][gtm] matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
version integer	Version number of the exception. Example: 1
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
id string	Unique ID that identifies this exception. Example: wbe_12345_HttDu2WDTmZg2xaQm6
rule string	The URL pattern, value, or expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net] Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.

Update a WebBlocker Exception

/{v1}/configuration/{accountid}/exceptions/webblocker/{objectid}

Make a request to this endpoint to update the specified WebBlocker exception with the data in the request body. When you update a WebBlocker exception, the version number increases by one.

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

objectid
string
REQUIRED

ID of the WebBlocker exception to update.

Example: wbe_12345_HttDu2WDTmZg2xaQm6

Request Body

version integer REQUIRED	Version number of the WebBlocker exception to update. Example: 1
action string REQUIRED	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
name string REQUIRED	Name of the WebBlocker exception. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: Allow example.com
rule-type string REQUIRED	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, \.[onc][eor][gtm] matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
rule string REQUIRED	The URL pattern, value, or regular expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net] Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.

Example Request

This request updates the WebBlocker exception with an objectid of wbe_12345_HttDu2WDTmZg2xaQm6:

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/webblocker/wbe_12345_HttDu2WDTmZg2xaQm6 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"version": 1,
	"action": "allow",
	"alarm": false,
	"name": "Allow watchguard.com",
	"rule_type": "pattern",
	"rule": "www.watchguard.com/*"
	}'

Example Response

The response includes the updated WebBlocker exception object in JSON format:

{
"object": "webblocker_exception",
"name": "Allow watchguard.com",
"created": 1583019217,
"device": 12345,
"rule_type": "pattern",
"version": 2,
"alarm": false,
"account": "WGC-1-123abc456",
"id": "wbe_12345_HttDu2WDTmZg2xaQm6",
"rule": "wwww.watchguard.com/*",
"author": "",
"action": "allow"
}

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

object string	Type of exception object. Example: webblocker_exception
name string	Name of the WebBlocker exception. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: Allow example.com
created integer	Time that the WebBlocker exception was created, specified in Unix epoch time format. Example: 1579907960
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
rule-type string	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, \.[onc][eor][gtm] matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
version integer	Version number of the exception. Example: 1
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
id string	Unique ID that identifies this exception. Example: wbe_12345_HttDu2WDTmZg2xaQm6
rule string	The URL pattern, value, or expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net]. Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.

Delete a WebBlocker Exception

/{v1}/configuration/{accountid}/exceptions/webblocker/{objectid}

Make a request to this endpoint to delete the specified WebBlocker exception. When you delete a WebBlocker exception, the version number increases by one and an inactive parameter with a value of true is added to the object.

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

objectid
string
REQUIRED

ID of the WebBlocker exception to delete.

Example: wbe_12345_HttDu2WDTmZg2xaQm6

Example Request

This request deletes the WebBlocker exception with an objectid of wbe_12345_HttDu2WDTmZg2xaQm6:

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/exceptions/webblocker/wbe_12345_HttDu2WDTmZg2xaQm6 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes the deleted WebBlocker exception in JSON format:

{
"object": "webblocker_exception",
"name": "Allow watchguard.com",
"rule": "wwww.watchguard.com/*",
"inactive": true,
"device": 12345,
"rule_type": "pattern",
"version": 3,
"alarm": false,
"account": "WGC-1-123abc456",
"id": "wbe_12345_HttDu2WDTmZg2xaQm6",
"created": 1583019217,
"author": "",
"action": "allow"
}

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

object string	Type of exception object. Example: webblocker_exception
name string	Name of the WebBlocker exception. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: Allow example.com
rule string	The URL pattern, value, or expression to match. Maximum: 255 characters. Examples: www.example.com/* 1.1.1.1 (www\\.)?example\\.[com\|net] Some special characters in regular expressions, such as the backslash, are reserved in JSON. Make sure to escape these characters in any JSON data you submit with a request.
inactive boolean	Indicates whether the exception is inactive. The value is always true for deleted exceptions. Example: true
device integer string	Device this exception applies to. Example: 12345, FBCL-12345
rule-type string	The type of rule. This can be one of these values: string — Matches an exact URL or IP address, character by character. You cannot use wildcards, and you must type each character exactly as you want it to be matched. For example, if you enter an exception to allow www.example.com as an exact match only, and a user types “www.example.com/news”, the request is denied. pattern — Matches a pattern in the URL or IP address, for example “pattern” in www.pattern.com. Make sure to drop the leading “http://” and include “/" at the end. Use the wildcard symbol, , to match any character. You can use more than one wildcard in one pattern. regexp — Uses a Perl-compatible regular expression to make a match. For example, \.[onc][eor][gtm] matches .org, .net, .com, or any other three-letter combination of one letter from each bracket, in order. When you create a regular expression to match URL paths, do not include the leading “http://”. Regular expressions support wildcards used in shell scripts. Example: string
version integer	Version number of the exception. Example: 1
alarm boolean	Specifies whether the Firebox sends an alarm for the WebBlocker exception. The default value is false. Example: true
account string	Your WatchGuard Cloud account ID. Example: WGC-1-123abc456 or ACC-1234567
id string	Unique ID that identifies this exception. Example: wbe_12345_HttDu2WDTmZg2xaQm6
created integer	Time that the WebBlocker exception was created, specified in Unix epoch time format. Example: 1579907960
author string	Author of the exception. This is always empty for exceptions added or updated with the Firebox Management API.
action string	Action to take for the WebBlocker exception. This can be one of these values: allow — Allows the request. The requested website opens. deny — Denies the request. The website does not open. A deny page appears in the browser.

Deployments

To update a device with the configuration changes saved in your WatchGuard Cloud account, you must create a deployment for the device. Each deployment creates a transaction record, which includes details of the deployment.

When you create a deployment for a device, all configuration changes saved in WatchGuard Cloud for that device will be deployed at the specified time. For example, if you used the Firebox Management API to delete a WebBlocker exception from WatchGuard Cloud for a device, the deployment deletes that exception from the device.

At the specified deployment time, WatchGuard Cloud notifies the device that configuration changes are available. The device then connects to WatchGuard Cloud, retrieves the configuration updates, and applies them. If the device is offline at the scheduled update time, it retrieves and applies the configuration updates the next time it connects to WatchGuard Cloud.

You can use the Firebox Management API to create deployments and retrieve transaction records. You can also update or cancel transactions for deployments that are scheduled to start in the future.

Endpoints:

/{v1}/commands/{accountid}/deployments

/{v1}/commands/{accountid}/transactions

/{v1}/commands/{accountid}/transactions/{objectid}

Create a New Device Deployment

/{v1}/commands/{accountid}/deployments

Make a request to this endpoint to deploy the configuration changes saved in WatchGuard Cloud to the specified devices. You can specify whether to deploy the configuration changes immediately or at a specific time in the future.

If you want to redeploy a previous deployment to the device, include the optional version parameter in your request. The Firebox Management API redeploys the deployment object with the specified version to the device. The transaction record for a specific device deployment includes the version number in the data parameter. For more information, see Retrieve a Transaction Record.

The response to this request includes a transaction record for the deployment. If you create a deployment for multiple devices, the Firebox Management API creates a parent transaction record and additional child transaction records for each device. For example, if you create a deployment for three devices, the response includes one parent transaction record and three child transaction records. The parent and children parameters in a transaction record include the IDs of related transactions.

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

Request Body

version integer	Version number of the device deployment to deploy. Only specify a version if you want to redeploy a previous deployment to the device. This will override the previous deployment to the device. Example: 1
start_date string REQUIRED	Time to deploy to the specified devices. Specify `now` to deploy immediately or specify a time in UTC format to deploy at that time. Example: 2020-04-19T21:23:46Z
description string	Description of the device deployment. Maximum: 128 characters. Example: Deploy exceptions to Seattle office Fireboxes.
devices array REQUIRED	Device(s) to deploy to. Each device has a unique ID number in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, your device ID is FB-12345. For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Enclose in square brackets and separate device IDs with commas. Example: [12345,12346,12347] You can specify a maximum of 50 devices in the list.

Example Request

This request deploys the configuration changes saved in WatchGuard Cloud for device 12345 immediately:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/WGC-1-123abc456/deployments 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"start_date": "now",
	"description": "Deploy exceptions to Seattle office",
	"devices":[12345]
	}'

Example Response

The response includes a list of transaction records for the deployment:

[
    {
        "account": "WGC-1-4b0079544acb4248be33",
        "author": "",
        "author_username": "",
        "created": 1723169573,
        "deployment_version": 17,
        "description": "Deploy exceptions to Seattle office Fireboxes.",
        "device": "101292",
        "id": "ddply_101292_BR5yl5o5KCAymR9",
        "inception_time": 1723169573,
        "metadata": {
            "device_asof": "2024-08-09T02:12:53Z",
            "new_flow": true
        },
        "object": "device_deployment",
        "original_author": "",
        "original_author_username": "",
        "referencedby": [],
        "references": [],
        "start_date": "now",
        "status": "imaged",
        "version": 2
    }
]

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

account string	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
original_author_username string	Operator that added the transaction. This is always empty for transactions added with the Firebox Management API.
id string	Unique ID that identifies this transaction. This includes the time when the deployment will occur, in Unix epoch time format. For parent transactions, the ID includes the text "parent". For child transactions, the ID includes the device id. Example: ddply_12345_J2VwPbXuek3CRGN1
status string	Status of the transaction. This can be one of these statuses: scheduled — Deployment is scheduled to start at the time specified by the `start_date` parameter. pending — Deployment executed but the device has not retrieved the configuration changes yet. in_progress — Deployment executed and the device is retrieving the configuration changes. complete — Deployment executed and the device successfully retrieved the configuration changes. failed — Deployment failed. imaged — A pending or in progress deployment timed out. Example: complete
start_date string	Time to deploy the transaction to the device, in UTC format. Example: 2020-02-21T19:48:19Z
object string	Device object type. Example: device_deployment
device string	Device this transaction applies to. Each device has a unique ID number in WatchGuard Cloud that appears in the URL of the Device Summary page. Example: 12345
inception_time integer	Time that the transaction was created, in seconds since epoch. Example: 1714684162
created string	Time that the transaction was created, in UTC format. Example: 1723169573
deployment_version string	Version number of the deployment. Example: 17
description string	Description of the device deployment. Maximum: 128 characters. Example: Deploy exceptions to Seattle office Fireboxes.

Query All Transaction Records

/{v1}/commands/{accountid}/transactions/

Make a request to this endpoint to retrieve all transaction records, which include details of individual deployments.

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

Request Parameters

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

device
integer
string

Device to retrieve transaction records for.

Each device has a unique ID number in WatchGuard Cloud, which appears in the URL of the Device Summary page. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, your device ID is FB-12345.

For standalone Fireboxes, specify only the numbers from the device ID. For example, 12345.

For FireClusters, specify the full device ID. For example, FBCL-12345.

Example: 12345, FBCL-12345

tx_type
string
REQUIRED

Specifies the type of transaction records to retrieve.

Example: deployment

Example Request

This request retrieves the transaction records for the device with an id of 12345.

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/WGC-1-123abc456/transactions?device=12345&tx_type=deployment 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes the transaction records that match the query:

{
    "count": 887,
    "more": false,
    "objects": [
        {
            "account": "WGC-1-4b0079544acb4248be33",
            "author": "",
            "author_username": "",
            "confirmed_date": "2024-07-30T08:21:11Z",
            "created": 1722327674,
            "deployment_version": 45,
            "description": "Template subscription update",
            "device": "100243",
            "id": "ddply_100243_03vvNbGqJr1OxrE",
            "inception_time": 1722327662,
            "metadata": {
                "device_asof": "2024-07-19T16:26:06Z",
                "hold_reason": null,
                "new_flow": true,
                "prev_ddply": "ddply_100243_TpXxgZZiFT2lNbT",
                "prev_version": "ddply_100243_TpXxgZZiFT2lNbT",
                "source": "brainiac",
                "subscription_change": true,
                "template_initiated": true,
                "tmpl_data": {
                    "author": "C5WwdZDUEUOOG+HyPui1MA==",
                    "author_username": "fccm-qa-owner",
                    "subscribe_templates": [
                        "WGC-1-4b0079544acb4248be33/tmpl_100243_ztZxPlAPY67XhVic"
                    ]
                }
            },
            "object": "device_deployment",
            "original_author": "",
            "original_author_username": "",
            "referencedby": [],
            "references": [],
            "start_date": "2024-07-30T08:21:02Z",
            "status": "complete",
            "version": 1
        },
        {
            "account": "WGC-1-4b0079544acb4248be33",
            "author": "",
            "author_username": "",
            "confirmed_date": "2024-07-17T04:02:17Z",
            "created": 1721189001,
            "deployment_version": 25,
            "description": "Deploy exceptions to Seattle office Fireboxes.",
            "device": "100243",
            "id": "ddply_100243_1p25JB2Po2y1BOz",
            "inception_time": 1721188862,
            "metadata": {
                "device_asof": "2024-07-17T04:01:02Z",
                "hold_reason": null,
                "initial": true,
                "new_flow": true,
                "scope": "FB"
            },
            "object": "device_deployment",
            "original_author": "C5WwdZDUEUOOG+HyPui1MA==",
            "original_author_username": "fccm-qa-owner",
            "referencedby": [],
            "references": [],
            "start_date": "2024-07-17T04:01:02Z",
            "status": "complete",
            "version": 2
        },
        {
            "account": "WGC-1-4b0079544acb4248be33",
            "author": "",
            "author_username": "",
            "confirmed_date": "2024-07-15T06:07:07Z",
            "created": 1721023630,
            "deployment_version": 21,
            "description": "Deploy exceptions to Seattle office Fireboxes.",
            "device": "100243",
            "id": "ddply_100243_2EkJ5xo7yYGsOH0",
            "inception_time": 1721023618,
            "metadata": {
                "device_asof": "2024-07-15T06:06:58Z",
                "hold_reason": null,
                "new_flow": true,
                "scope": "FB"
            },
            "object": "device_deployment",
            "original_author": "C5WwdZDUEUOOG+HyPui1MA==",
            "original_author_username": "fccm-qa-owner",
            "referencedby": [],
            "references": [],
            "start_date": "2024-07-15T06:06:58Z",
            "status": "complete",
            "version": 2
        }

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

account string	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
original_author_username string	Operator that added the transaction. This is always empty for transactions added with the Firebox Management API.
id string	Unique ID that identifies this transaction. This includes the time when the deployment will occur, in Unix epoch time format. For parent transactions, the ID includes the text "parent". For child transactions, the ID includes the device id. Example: ddply_12345_J2VwPbXuek3CRGN1
status string	Status of the transaction. This can be one of these statuses: scheduled — Deployment is scheduled to start at the time specified by the `start_date` parameter. pending — Deployment executed but the device has not retrieved the configuration changes yet. in_progress — Deployment executed and the device is retrieving the configuration changes. complete — Deployment executed and the device successfully retrieved the configuration changes. failed — Deployment failed. imaged — A pending or in progress deployment timed out. Example: complete
start_date string	Time to deploy the transaction to the device, in UTC format. Example: 2020-02-21T19:48:19Z
object string	Device object type. Example: device_deployment
device string	Device this transaction applies to. Each device has a unique ID number in WatchGuard Cloud that appears in the URL of the Device Summary page. Example: 12345
inception_time integer	Time that the transaction was created, in seconds since epoch. Example: 1714684162
created string	Time that the transaction was created, in UTC format. Example: 1723169573
deployment_version string	Version number of the deployment. Example: 17
description string	Description of the device deployment. Maximum: 128 characters. Example: Deploy exceptions to Seattle office Fireboxes.

Retrieve a Transaction Record

/{v1}/commands/{accountid}/transactions/{objectid}

Make a request to this endpoint to retrieve the specified transaction record, which includes details of a specific deployment.

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

objectid
string
REQUIRED

ID of the transaction record to retrieve.

Example: ddply_12345_J2VwPbXuek3CRGN1

Example Request

This request retrieves the transaction record with an objectid of ddply_12345_J2VwPbXuek3CRGN1.

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/WGC-1-123abc456/transactions/ddply_12345_J2VwPbXuek3CRGN1 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes the specified transaction record:

{
    "account": "WGC-1-4b0079544acb4248be33",
    "author": "",
    "author_username": "",
    "confirmed_date": "2024-08-09T02:12:57Z",
    "created": 1723169579,
    "deployment_version": 17,
    "description": "Deploy exceptions to Seattle office Fireboxes.",
    "device": "101292",
    "id": "ddply_101292_BR5yl5o5KCAymR9",
    "inception_time": 1723169573,
    "metadata": {
        "device_asof": "2024-08-09T02:12:53Z",
        "hold_reason": null,
        "new_flow": true
    },
    "object": "device_deployment",
    "original_author": "",
    "original_author_username": "",
    "referencedby": [],
    "references": [],
    "start_date": "2024-08-09T02:12:53Z",
    "status": "complete",
    "version": 2
}

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

account string	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
original_author_usernameoperator string	Operator that added the transaction. This is always empty for transactions added with the Firebox Management API.
id string	Unique ID that identifies this transaction. This includes the time when the deployment will occur, in Unix epoch time format. For parent transactions, the ID includes the text "parent". For child transactions, the ID includes the device id. Examples: ddply_12345_J2VwPbXuek3CRGN1deployment_12345_1582314499_zRmCUMqFghS5oCLmRcWtshBI deployment_parent_1583862246_IfKUIDAZAs8uEJAYYF6eDDuL
status string	Status of the transaction. This can be one of these statuses: scheduled — Deployment is scheduled to start at the time specified by the `start_date` parameter. pending — Deployment executed but the device has not retrieved the configuration changes yet. in_progress — Deployment executed and the device is retrieving the configuration changes. complete — Deployment executed and the device successfully retrieved the configuration changes. failed — Deployment failed. imagedtimed_out — A pending or in progress deployment timed out. canceled — Transaction record was deleted before the deployment executed. Example: complete
start_date string	Time to deploy the transaction to the device, in UTC format. Example: 2020-02-21T19:48:19Z
objecttype string	Device object transaction type. Example: device_deployment
device string	Device this transaction applies to. Each device has a unique ID number in WatchGuard Cloud that appears in the URL of the Device Summary page. Example: 12345
inception_time integers	Time that the transaction was created, in seconds since epoch. Example: 1714684162
created string	Time that the transaction was created, in UTC format. Example: 1723169573
deployment_version string	Version number of the deployment. Example: 17
description string	Description of the device deployment. Maximum: 128 characters. Example: Deploy exceptions to Seattle office Fireboxes.

Update a Transaction

/{v1}/commands/{accountid}/transactions/{objectid}

Make a request to this endpoint to update the start date of the specified transaction, which includes details of a specific deployment. Optionally, you can also update the description of the transaction.

You can only update scheduled transactions with a start date in the future.

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

objectid
string
REQUIRED

ID of the transaction record to update.

Example: ddply_12345_J2VwPbXuek3CRGN1

Request Body

start_date
string
REQUIRED

Time to deploy to the specified devices. Specify now to deploy immediately or specify a time in UTC format to deploy at that time.

Example: 2020-04-19T21:23:46Z

description
string

Description of the device deployment. Maximum: 128 characters.

Example: Deploy exceptions to Seattle office Fireboxes.

Example Request

This request updates the start_date and description of the transaction with an objectid of ddply_12345_J2VwPbXuek3CRGN1.

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/WGC-1-123abc456/transactions/ddply_12345_J2VwPbXuek3CRGN1 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
	-d '{
	"start_date": "2020-06-1T21:23:46Z",
	"description": "Deploy to Seattle office Firebox"
	}'

Example Response

The response includes the updated transaction record:

{
    "account": "WGC-1-4b0079544acb4248be33",
    "author": "",
    "author_username": "",
    "created": 1723169955,
    "description": "Deploy exceptions to Seattle office Fireboxes.",
    "device": "101292",
    "id": "ddply_101292_v02rOiK5UOXKafo",
    "inception_time": 1723169914,
    "metadata": {
        "job_id": 175790,
        "job_name": "ddply_101292_v02rOiK5UOXKafo_1723169914",
        "new_flow": true
    },
    "object": "device_deployment",
    "original_author": "",
    "original_author_username": "",
    "referencedby": [],
    "references": [],
    "start_date": "2024-08-10T06:00:00Z",
    "status": "scheduled",
    "version": 3
}

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

account string	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
original_author_username string	Operator that added the transaction. This is always empty for transactions added with the Firebox Management API.
id string	Unique ID that identifies this transaction. This includes the time when the deployment will occur, in Unix epoch time format. For parent transactions, the ID includes the text "parent". For child transactions, the ID includes the device id. Example: ddply_12345_J2VwPbXuek3CRGN1
status string	Status of the transaction. This can be one of these statuses: scheduled — Deployment is scheduled to start at the time specified by the `start_date` parameter. pending — Deployment executed but the device has not retrieved the configuration changes yet. in_progress — Deployment executed and the device is retrieving the configuration changes. complete — Deployment executed and the device successfully retrieved the configuration changes. failed — Deployment failed. imaged — A pending or in progress deployment timed out. Example: complete
start_date string	Time to deploy the transaction to the device, in UTC format. Example: 2020-02-21T19:48:19Z
object string	Device object type. Example: device_deployment
device string	Device this transaction applies to. Each device has a unique ID number in WatchGuard Cloud that appears in the URL of the Device Summary page. Example: 12345
inception_time integer	Time that the transaction was created, in seconds since epoch. Example: 1714684162
created string	Time that the transaction was created, in UTC format. Example: 1723169573
deployment_version string	Version number of the deployment. Example: 17
description string	Description of the device deployment. Maximum: 128 characters. Example: Deploy exceptions to Seattle office Fireboxes.

Cancel a Transaction

/{v1}/commands/{accountid}/transactions/{objectid}

Make a request to this endpoint to cancel the specified transaction, which includes details of a specific deployment. You might cancel a transaction if you decide that you do not want to deploy the configuration changes it includes to a device. Devices do not retrieve canceled transactions.

You can only cancel transactions that have not yet deployed to a device, such as those with a status of pending or scheduled.

Transaction records for canceled transactions have a status of canceled and remain in the database.

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

objectid
string
REQUIRED

ID of the transaction record to cancel.

Example: ddply_12345_J2VwPbXuek3CRGN1

Example Request

This request cancels the transaction with an objectid of ddply_12345_J2VwPbXuek3CRGN1.

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/WGC-1-123abc456/transactions/ddply_12345_J2VwPbXuek3CRGN1 
	-H 'Accept: application/json'
	-H 'Content-Type: application/json' 
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjNDQyMTJlMi05MmI1LTRiOTYtYTRmNS1lYWRlODA4OTM1YjIiLCJjdXN0b206YXBpX2tleXMiOiJwMHM1UmQzUkF2NlR2d0VuWEx5YUphR2x0ZWtieEFVUzcwVGVzOXlGIiwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tXC91cy13ZXN0LTJfa3hXeFdrTFZ5IiwiY29nbml0bzp1c2VybmFtZSI6IjAyNjk0OWM1OWI2NzIxOGNfcndfaWQiLCJhdWQiOiIzb3AybDBqazkxN3FudXFoZnVoanRvcXRzZyIsImV2ZW50X2lkIjoiODczM2ZmMjktOGNhMC00ODMyLTg0NzgtMDNiNWIxMDI3NmQ3IiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1NjkzNTM0NDEsIm5hbWUiOiIwMjY5NDljNTliNjcyMThjX3J3X2lkIiwiY3VzdG9tOmFjY291bnRfaWQiOiJBQ0MtMTIzNTA2OCIsImV4cCI6MTU2OTM1NzA0MSwiY3VzdG9tOnJvbGUiOiIxIiwiaWF0IjoxNTY5MzUzNDQxfQ.MUAeG6QyM7Zog8mM--WK2uJVevLRwz8z2KPpGhQbUnHK04Hy_JdO4F4wH6IV0WVENGsBrcjp5boxcBZgdJE46123MGnB0HvghN5IoAZUOkfFPm7SAN68posHqYLoo14YNedc5GtvOzCxTmi9YepvE5LhsoC6Tgyc0e3ABn18gEZsyxmJFcMBHXOMei7AssYSWAdDyoI7j6jZslxmhXj7_h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response includes the canceled transaction record:

{
    "account": "WGC-1-4b0079544acb4248be33",
    "author": "",
    "author_username": "",
    "created": 1723169986,
    "description": "Deploy exceptions to Seattle office Fireboxes.",
    "device": "101292",
    "id": "ddply_101292_v02rOiK5UOXKafo",
    "inactive": true,
    "inception_time": 1723169914,
    "metadata": {
        "job_id": 175790,
        "job_name": "ddply_101292_v02rOiK5UOXKafo_1723169914",
        "new_flow": true
    },
    "object": "device_deployment",
    "original_author": "",
    "original_author_username": "",
    "referencedby": [],
    "references": [],
    "start_date": "2024-08-10T06:00:00Z",
    "status": "scheduled",
    "version": 4
}

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

account string	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
original_author_username string	Operator that added the transaction. This is always empty for transactions added with the Firebox Management API.
id string	Unique ID that identifies this transaction. This includes the time when the deployment will occur, in Unix epoch time format. For parent transactions, the ID includes the text "parent". For child transactions, the ID includes the device id. Example: ddply_12345_J2VwPbXuek3CRGN1
status string	Status of the transaction. This can be one of these statuses: scheduled — Deployment is scheduled to start at the time specified by the `start_date` parameter. pending — Deployment executed but the device has not retrieved the configuration changes yet. in_progress — Deployment executed and the device is retrieving the configuration changes. complete — Deployment executed and the device successfully retrieved the configuration changes. failed — Deployment failed. imaged — A pending or in progress deployment timed out. Example: complete
start_date string	Time to deploy the transaction to the device, in UTC format. Example: 2020-02-21T19:48:19Z
object string	Device object type. Example: device_deployment
device string	Device this transaction applies to. Each device has a unique ID number in WatchGuard Cloud that appears in the URL of the Device Summary page. Example: 12345
inception_time integer	Time that the transaction was created, in seconds since epoch. Example: 1714684162
created string	Time that the transaction was created, in UTC format. Example: 1723169573
deployment_version string	Version number of the deployment. Example: 17
description string	Description of the device deployment. Maximum: 128 characters. Example: Deploy exceptions to Seattle office Fireboxes.