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
Create and manage Branch Office VPNs (BOVPN)
Create and manage account certificates and Firebox certificates
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 use the BOVPN and Certificate APIs with a cloud-managed Firebox, the device must run Fireware v12.5.7 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.

Branch Office VPNs (BOVPNs)

A Branch Office Virtual Private Network (BOVPN) enables secure, encrypted connections between networks at geographically separated locations. You can configure an IPSec BOVPN tunnel between cloud-managed Fireboxes in your WatchGuard Cloud account or from a cloud-managed Firebox to any other Firebox or third-party VPN endpoint. For more information, go to Manage BOVPNs for Cloud-Managed Fireboxes.

BOVPN API operations work only with cloud‑managed Fireboxes that store configuration in WatchGuard Cloud. They do not work with locally‑managed Fireboxes, including those with WatchGuard Cloud reporting, because these devices store no configuration in WatchGuard Cloud. The API returns an empty response for locally‑managed Fireboxes.

This API does not automatically deploy BOVPN configuration changes to the Firebox. To apply these changes, you must manually deploy them from the WatchGuard Cloud UI or through a separate public API call. For more information, go to Deployments.

You can use the Firebox Management API to:

Get a BOVPN Tunnel
Create a BOVPN Tunnel
Edit a BOVPN Tunnel
Modify Routes and Certificates
Delete a BOVPN Tunnel
Manage Shared Phase 1 Settings

Endpoints:

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

/{v1}/configuration/{accountid}/bovpn/ipsec/p1_shared_settings

Get a BOVPN Tunnel

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels?device={device}

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

Make a request to this endpoint to retrieve information about BOVPN tunnels. You can retrieve BOVPN tunnels for a specific account, device, or tunnel ID. The information you must provide in the request depends on the BOVPN tunnels you want to retrieve:

Retrieve a list of all BOVPN tunnels for a WatchGuard account

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels

Make a request to this endpoint to retrieve BOVPN tunnel information for a specific account.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

Example Request

This example requests a list of the BOVPN tunnels for an account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/tunnels
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXIn0.eyJzdWIiOiN0LTJfa3hXeFdfU650heiAaUAy7XmiqbA'

Retrieve a list of all BOVPN tunnels for a device

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels?device={device}

Make a request to this endpoint to retrieve BOVPN tunnel information for a specific Firebox.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

Query Parameters

device
string
integer
REQUIRED

Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. The device ID can be a string or an integer for a standalone device. 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 or 12345.

Example: 12345

For FireClusters, specify the full device ID.

Example: FBCL-12345.

Example Request

This request retrieves the list of BOVPN tunnels for a device.


curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/tunnels?device=12345
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXIn0.eyJzdWIiOiN0LTJfa3hXeFdfU650heiAaUAy7XmiqbA'

Retrieve a specific BOVPN tunnel

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

Make a request to this endpoint to retrieve information about a specific BOVPN tunnel.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

objectid
string
REQUIRED

Each BOVPN tunnel has a unique ID in WatchGuard Cloud, which appears in the URL of the BOVPN configuration page.

For example, if the BOVPN configuration page URL is https://usa.cloud.watchguard.com/ss-tenant/services/ACC-1234567/fb/device/FB-12345/configuration/bovpn/tunnel/ipsgp_123456DH, the tunnel ID is ipsgp_123456DH.

Example: ipsgp_123456DH

Example Request

This request retrieves a specific BOVPN tunnel from a device.


curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/tunnels/ipsgp_136162_2DPNyV3Tc4ZkpqK
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXIn0.eyJzdWIiOiN0LTJfa3hXeFdfU650heiAaUAy7XmiqbA'

Example Response

The response includes details of the requested BOVPN IPSec tunnels in JSON format:

{
"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaypair",
"version": 1,
"account": "WGC-1-123abc456",
"created": 1579907960,
"author": "testuser",
"name": "PBoVPN1",
"endpoint_a": "136162",
"endpoint_b_name": "CentralVPNServer",
"vpn_type": "route-based",
"address_family": 4,
"interfaces": [
	{
	"endpoint_a": {
		"network": "External"
	},
	"endpoint_b": {
		"id": {
			"type": "ip",
			"value": "192.88.99.200"
			}
		}
	}
],
"psk": "12345678",
"ipsec_tunnel_core": {
	"ike_proposals": [
	{
	"encryption": "AES-CBC-256",
	"dh_group": "DH-14",
	"lifetime": 24,
	"authentication": "SHA2-256"
	}
],
	"ipsec_proposals": [
		{
		"encryption": "AES-CBC-256",
		"lifetime": 8,
		"lifebyte": 0,
		"authentication": "SHA2-256"
	}
],
	"pfs_dh_group": "DH-14",
	"natt_interval": 20,
	"dpd": {
		"dpd_type": "traffic",
		"idle_time": 20,
		"retries": 5
	}
},
"routes": {
	"endpoint_a": {
		"local_routes": [
		{
		"metric": 1,
		"route": "192.168.1.0/24"
		}
	]
},
	"endpoint_b": {
		"local_routes": [
		{
		"metric": 6,
		"route": "192.168.100.0/24"
			}
		]
	}
},
	"vif": {
		"endpoint_a": {
			"vif_df_bit": "set",
			"vif_local_ip": "9.9.9.9/32",
			"vif_mtu": 1399,
			"vif_remote_ip": "10.10.10.10/32"
		},
		"endpoint_b": {
			"vif_local_ip": "10.10.10.10/32",
			"vif_remote_ip": "9.9.9.9/32"
		}
	}
}

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object returned. Example: ipsec_gatewaytemplate
version integer	Version number of the BOVPN. Example: 1
account string	WatchGuard Cloud account ID associated with this gateway pair. Example: WGC-1-123abc456
created integer	Unix time stamp of when the gateway pair was created. Example: 1579907960
author string	Author of the object. Empty for objects added or updated with the Firebox Management API.
name string	Name of the gateway pair. Example: PBoVPN1
endpoint_a string	Name of the cloud-managed Firebox. Example: 12345
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Defines the cloud-managed Firebox interface settings.
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
endpoint_b object	Identifies the remote device or endpoint that the cloud-managed Firebox (`endpoint_a`) connects to.
id object	Unique ID for the IPSec gateway.
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An IP address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
psk string	Pre-shared key (PSK) used for authentication between endpoints. Example: 24681012
ipsec_tunnel_core object	Phase 1 (IKE) and Phase 2 (IPSec) settings, Dead Peer Detection (DPD), and NAT-T keep-alive configurations for the tunnel.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
pfs_dh_group string	Diffie-Hellman (DH) group used for Perfect Forward Secrecy (PFS) in Phase 2 of the VPN tunnel. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect if the remote peer is no longer responsive.
dpd_type string	Dead Peer Detection type. This can be one of these values: traffic — Default. Based on traffic activity. If no traffic is detected for a specified idle time, DPD messages are sent. timer — Sent at regular intervals, regardless of traffic. Example: traffic
idle_time integer	Amount of time (in seconds) before the peer is considered idle. Specify a number of seconds from 10-300. Default value is 30. Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
routes object	Routes to establish through the tunnel.
endpoint_a object	Route object for the cloud-managed Firebox.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.1.0/24
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (`endpoint_a`) connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.100.0/24
vif object	Virtual interface configuration for each VPN endpoint.
endpoint_a object	Route object for the cloud-managed Firebox.
vif_df_bit string	Specifies the DF (Don't Fragment) bit value. This can be one of these values: copy — Copies the DF bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 10.10.10.10/32
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (`endpoint_a`) connects to.
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 10.10.10.10/32
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 9.9.9.9/32

Create a BOVPN Tunnel

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels

Make a request to this endpoint to configure a route-based or policy-based BOVPN IPSec tunnel between two devices. All tunnels require at least one cloud-managed Firebox endpoint.

Requests for policy-based and route-based BOVPNs have some differences. For policy-based BOVPNs, you must:

Set the value of the vpn_type parameter to policy-based.
Submit request parameters in the local_remote_pairs section instead of the routes section.
Not submit request parameters in the vif section, which does not apply for policy-based BOVPNs.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

The information you must provide in the request body depends on the type of BOVPN configuration you want to add:

Configure a route-based BOVPN tunnel that uses a pre-shared key

Request Body

When you send a request to this endpoint, include this information in the request body:

name string REQUIRED	Name of the BOVPN tunnel. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters Example: PBoVPN1
endpoint_a string REQUIRED	Unique device ID for the cloud-managed Firebox. You can find the device ID 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 12345. For a FireCluster, use the FBCL prefix (FBCL-12345). Example: 12345
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array REQUIRED	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Route object for the device.
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
endpoint_b object	Route object for the device that `endpoint_a` connects to.
id object	Unique ID for the IPSec gateway.
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An IP address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
psk string	Pre-shared key (PSK) used for authentication between endpoints. Example: 12345678
ipsec_tunnel_core object	Phase 1 (IKE) and Phase 2 (IPSec) settings, Dead Peer Detection (DPD), and NAT-T keep-alive configurations for the tunnel.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
ipsec_proposals array	Array of IPSec Phase 2 proposals.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 8. Example: 8
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
lifebyte integer	Maximum amount of data (in bytes) that you can be transmit through an IPSec Security Association (SA) before it expires and must rekey. Example: 0
authentication string	The hash algorithm used to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
pfs_dh_group string	Diffie-Hellman (DH) group used for Perfect Forward Secrecy (PFS) in Phase 2 of the VPN tunnel. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect if the remote peer is no longer responsive.
dpd_type string	Dead Peer Detection type. This can be one of these values: traffic — Default. Based on traffic activity. If no traffic is detected for a specified idle time, DPD messages are sent. timer — Sent at regular intervals, regardless of traffic. Example: traffic
idle_time integer	Amount of time (in seconds) before the peer is considered idle. Specify a number of seconds from 10-300. Default value is 30 Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
routes object REQUIRED	Routes to establish through the tunnel.
endpoint_a object	Route object for the device.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.1.0/24
endpoint_b object	Route object for the device that `endpoint_a` connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 6
route string	Route to establish through the tunnel. Example: 192.168.100.0/24
vif object	Virtual interface configuration for each VPN endpoint.
endpoint_a object	Route object for the device.
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 10.10.10.10/32
endpoint_b object	Route object for the device that `endpoint_a` connects to.
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 10.10.10.10/32
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 9.9.9.9/32

Example Request

This request configures a route-based BOVPN tunnel that uses a pre-shared key.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/{accountid}/bovpn/ipsec/tunnels 
-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 '{
"example1": {
"summary": "Create an IPSEC tunnel using PSK",
"value": {
	"name": "PBoVPN1",
	"endpoint_a": "136162",
	"endpoint_b_name": "CentralVPNServer",
	"vpn_type": "route-based",
	"address_family": 4,
	"interfaces": [
	{
	"endpoint_a": {
		"network": "External"
	},
	"endpoint_b": {
		"id": {
			"type": "ip",
			"value": "192.88.99.200"
			}
		}
	}
	],
"psk": "12345678",
"ipsec_tunnel_core": {
	"ike_proposals": [
	{
	"encryption": "AES-CBC-256",
	"dh_group": "DH-14",
	"lifetime": 24,
	"authentication": "SHA2-256"
	}
	],
"ipsec_proposals": [
	{
	"encryption": "AES-CBC-256",
	"lifetime": 8,
	"lifebyte": 0,
	"authentication": "SHA2-256"
	}
	],
"pfs_dh_group": "DH-14",
"natt_interval": 20,
"dpd": {
	"dpd_type": "traffic",
	"idle_time": 20,
	"retries": 5
	}
},
"routes": {
	"endpoint_a": {
		"local_routes": [
		{
			"metric": 1,
			"route": "192.168.1.0/24"
			}
		]
	},
	"endpoint_b": {
		"local_routes": [
		{
			"metric": 6,
			"route": "192.168.100.0/24"
			}
		]
	}
},
"vif": {
	"endpoint_a": {
		"vif_df_bit": "set",
		"vif_local_ip": "9.9.9.9/32",
		"vif_mtu": 1399,
		"vif_remote_ip": "10.10.10.10/32"
		},
	"endpoint_b": {
		"vif_local_ip": "10.10.10.10/32",
		"vif_remote_ip": "9.9.9.9/32"
		}
		}
	},
}'

Configure a route-based BOVPN tunnel that uses a certificate

Request Body

When you send a request to this endpoint, include this information in the request body:

name string REQUIRED	Name of the BOVPN tunnel. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: PBoVPN1
endpoint_a string REQUIRED	Unique device ID for the cloud-managed Firebox. You can find the device ID 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 12345. For a FireCluster, use the FBCL prefix (FBCL-12345). Example: 12345
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array REQUIRED	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Route object for the device.
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
endpoint_b object	Route object for the device that `endpoint_a` connects to.
id object	Unique ID for the IPSec gateway.
type string	Gateway endpoint ID type. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
certs object	Object of certificate references.
endpoint_a string	Certificate ID for endpoint A. Example: DeviceCertificateNam
ipsec_tunnel_core object	Phase 1 (IKE) and Phase 2 (IPSec) settings, Dead Peer Detection (DPD), and NAT-T keep-alive configurations for the tunnel.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
ipsec_proposals array	Array of IPSec Phase 2 proposals.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 8. Example: 8
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
lifebyte integer	Maximum amount of data (in bytes) that you can be transmit through an IPSec Security Association (SA) before it expires and must rekey. Example: 0
authentication string	The hash algorithm used to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
pfs_dh_group string	Diffie-Hellman (DH) group used for Perfect Forward Secrecy (PFS) in Phase 2 of the VPN tunnel. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect if the remote peer is no longer responsive.
dpd_type string	Dead Peer Detection type. This can be one of these values: traffic — Default. Based on traffic activity. If no traffic is detected for a specified idle time, DPD messages are sent. timer — Sent at regular intervals, regardless of traffic. Example: traffic
idle_time integer	Amount of time (in seconds) before the peer is considered idle. Specify a number of seconds from 10-300. Default value is 30 Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
routes object REQUIRED	Routes to establish through the tunnel.
endpoint_a object	Route object for the device.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.1.0/24
endpoint_b object	Route object for the device that `endpoint_a` connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 6
route string	Route to establish through the tunnel. Example: 192.168.100.0/24
vif object	Virtual interface configuration for each VPN endpoint.
endpoint_a object	Route object for the device.
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 10.10.10.10/32
endpoint_b object	Route object for the device that `endpoint_a` connects to.
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 10.10.10.10/32
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 9.9.9.9/32

Example Request

This request configures a route-based BOVPN tunnel that uses a certificate.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/{accountid}/bovpn/ipsec/tunnels 
-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 '{
"example2": {
"summary": "Create an IPSEC tunnel using a certificate.",
"value": {
	"name": "PBoVPN1",
	"endpoint_a": "136162",
	"endpoint_b_name": "CentralVPNServer",
	"vpn_type": "route-based",
	"address_family": 4,
	"interfaces": [
		{
		"endpoint_a": {
			"network": "External"
			},
		"endpoint_b": {
			"id": {
			"type": "ip",
			"value": "192.88.99.200"
				}
			}
		}
	],
	"certs": [
		{
		"endpoint_a": "DeviceCertificateName"
		}
	],
	"ipsec_tunnel_core": {
		"ike_proposals": [
		{
		"encryption": "AES-CBC-256",
		"dh_group": "DH-14",
		"lifetime": 24,
		"authentication": "SHA2-256"
		}
		],
	"ipsec_proposals": [
		{
		"encryption": "AES-CBC-256",
		"lifetime": 8,
		"lifebyte": 0,
		"authentication": "SHA2-256"
		}
		],
	"pfs_dh_group": "DH-14",
	"natt_interval": 20,
	"dpd": {
		"dpd_type": "traffic",
		"idle_time": 20,
		"retries": 5
		}
		},
	"routes": {
		"endpoint_a": {
			"local_routes": [
			{
			"metric": 1,
			"route": "192.168.1.0/24"
			}
		]
		},
		"endpoint_b": {
			"local_routes": [
			{
			"metric": 6,
			"route": "192.168.100.0/24"
			}
			]
		}
		},
	"vif": {
		"endpoint_a": {
			"vif_df_bit": "set",
			"vif_local_ip": "9.9.9.9/32",
			"vif_mtu": 1399,
			"vif_remote_ip": "10.10.10.10/32"
			},
		"endpoint_b": {
			"vif_local_ip": "10.10.10.10/32",
			"vif_remote_ip": "9.9.9.9/32"
			}
		}
	}
	}
}'

Example Response

This response includes the route-based BOVPN tunnel that uses a pre-shared key in JSON format:

{
"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaypair",
"version": 1,
"account": "WGC-1-123abc456",
"created": 1579907960,
"author": "testuser",
"name": "PBoVPN1",
"endpoint_a": "136162",
"endpoint_b_name": "CentralVPNServer",
"vpn_type": "route-based",
"address_family": 4,
"interfaces": [
	{
	"endpoint_a": {
		"network": "External"
		},
	"endpoint_b": {
		"id": {
		"type": "ip",
		"value": "192.88.99.200"
		}
	}
	}
],
"psk": "12345678",
"ipsec_tunnel_core": {
	"ike_proposals": [
	{
	"encryption": "AES-CBC-256",
	"dh_group": "DH-14",
	"lifetime": 24,
	"authentication": "SHA2-256"
	}
],
"ipsec_proposals": [
	{
	"encryption": "AES-CBC-256",
	"lifetime": 8,
	"lifebyte": 0,
	"authentication": "SHA2-256"
	}
	],
"pfs_dh_group": "DH-14",
"natt_interval": 20,
"dpd": {
	"dpd_type": "traffic",
	"idle_time": 20,
	"retries": 5
	}
},
"routes": {
	"endpoint_a": {
		"local_routes": [
			{
			"metric": 1,
			"route": "192.168.1.0/24"
		}
	]
},
	"endpoint_b": {
		"local_routes": [
			{
			"metric": 6,
			"route": "192.168.100.0/24"
			}
		]
	}
},
"vif": {
	"endpoint_a": {
		"vif_df_bit": "set",
		"vif_local_ip": "9.9.9.9/32",
		"vif_mtu": 1399,
		"vif_remote_ip": "10.10.10.10/32"
	},
	"endpoint_b": {
		"vif_local_ip": "10.10.10.10/32",
		"vif_remote_ip": "9.9.9.9/32"
	}
	}
}

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object returned. Example: ipsec_gatewaytemplate
version integer	Version number of the BOVPN. Example: 1
account string	WatchGuard Cloud account ID associated with this gateway pair. Example: WGC-1-123abc456
created integer	Unix time stamp when the gateway pair was created. Example: 1579907960
author string	Author of the gateway pair. Example: YourName
name string	Name for the gateway pair. Example: PBoVPN1
endpoint_a string	Name of the cloud-managed Firebox. Example: 136162
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Route object for the device.
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
endpoint_b object	Route object for the remote device or endpoint that `endpoint_a` connects to.
id object	Unique ID for the IPSec gateway.
type string	Gateway endpoint ID type. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
psk string	Pre-shared key (PSK) used for authentication between endpoints. Example: 12345678
ipsec_tunnel_core object	Phase 1 (IKE) and Phase 2 (IPSec) settings, Dead Peer Detection (DPD), and NAT-T keep-alive configurations for the tunnel.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
ipsec_proposals array	Array of IPSec Phase 2 proposals.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 Example: AES-GCM-256
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 8. Example: 8
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
lifebyte integer	Maximum amount of data (in bytes) that you can be transmit through an IPSec Security Association (SA) before it expires and must rekey. Example: 0
authentication string	The hash algorithm used to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
pfs_dh_group string	Diffie-Hellman (DH) group used for Perfect Forward Secrecy (PFS) in Phase 2 of the VPN tunnel. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect if the remote peer is no longer responsive.
dpd_type string	Dead Peer Detection type. This can be one of these values: traffic — Default. Based on traffic activity. If no traffic is detected for a specified idle time, DPD messages are sent. timer — Sent at regular intervals, regardless of traffic. Example: traffic
idle_time integer	Amount of time (in seconds) before the peer is considered idle. Specify a number of seconds from 10-300. Default value is 30 Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
routes object	Routes to establish through the tunnel.
endpoint_a object	Route object for the device.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.1.0/24
endpoint_b object	Route object the remote device or endpoint that `endpoint_a` connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.100.0/24
vif object	Virtual interface configuration for each VPN endpoint.
endpoint_a object	Route object for the device.
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 10.10.10.10/32
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (`endpoint_a`) connects to.
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 10.10.10.10/32
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 9.9.9.9/32

Edit a BOVPN Tunnel

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

Make a request to this endpoint to update a BOVPN IPSec tunnel configuration by name or by unique object ID.

Update a BOVPN IPSec tunnel by name

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/

Make a request to this endpoint to update an existing BOVPN configuration by name.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

Request Body

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

version integer REQUIRED	Version number of the BOVPN. Example: 1
name string REQUIRED	Name of the BOVPN tunnel. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: PBoVPN1
endpoint_a string REQUIRED	Unique device ID for the cloud-managed Firebox. You can find the device ID 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 12345. For a FireCluster, use the FBCL prefix (FBCL-12345). Example: 12345
endpoint_b string	Identifies the remote device or endpoint that endpoint_a connects to. Example: 67890
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
disabled boolean	Indicates whether the IPSec tunnel is disabled. Default is false. Example: false
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
auth_method string	Local authentication method for the tunnel. Default is `psk`. This can be one of these values: psk certificate Example: psk
interfaces array REQUIRED	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Defines the cloud-managed Firebox interface settings.
network string	Network definition for the tunnel (External \| Trusted \| Optional).
ip_address string	IP address of endpoint A interface; can be a literal address or `Dynamic`.
id object	Unique ID for the IPSec gateway.
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
perpetual_resolve boolean	Enable to re-resolve domains when you rebuild tunnels. Example: true
endpoint_b object	Defines the remote VPN gateway interface settings.
network string	Network definition for the tunnel (External \| Trusted \| Optional).
ip_address string	IP address of endpoint B interface; can be a literal address or `Dynamic`.
id object	Unique ID for the IPSec gateway.
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
perpetual_resolve boolean	Enable to re-resolve domains when you rebuild tunnels. Example: true
df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
pmtu_minimum integer	Minimum Path MTU threshold for each endpoint (68 to1550 bytes). Example:1550
pmtu_age integer	Path MTU aging time for each endpoint in minutes (60 to 2147483647 minutes). Example: 2147483647
routes object REQUIRED	Routes to establish through the tunnel.
endpoint_a object	Route object for the cloud-managed Firebox .
local_networks array	Local network segments that are accessible through the VPN tunnel.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
nat_base string	Specifies the source network for NAT. Must be in IPv4 CIDR format. Example: 192.0.2.0/24
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
dnat_ip string	Specifies an optional destination NAT. Example: 192.0.2.1
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
nat_base string	Specifies the source network for NAT. Must be in IPv4 CIDR format. Example: 192.0.2.0/24
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.0.2.0/24
dnat_ip string	Specifies an optional destination NAT. Example: 192.0.2.1
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (endpoint_a) connects to.
local_networks array	Local network segments that are accessible through the VPN tunnel.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
nat_base string	Specifies the source network for NAT. Must be in IPv4 CIDR format. Example: 192.0.2.0/24
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
dnat_ip string	Specifies an optional destination NAT. Example: 192.0.2.1
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
nat_base string	Specifies the source network for NAT. Must be in IPv4 CIDR format. Example: 192.0.2.0/24
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.0.2.0/24
dnat_ip string	Specifies an optional destination NAT. Example: 192.0.2.1
vif object	Virtual interface configuration for each VPN endpoint.
endpoint_a object	Route object for the cloud-managed Firebox.
vif_dev_name string	Name of the virtual interface.
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 10.10.10.10/32
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (`endpoint_a`) connects to.
vif_dev_name string	Name of the virtual interface.
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 10.10.10.10/32
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
certs object	Object of certificate references.
endpoint_a string	Certificate name for endpoint A. Example: DeviceCertificateName
endpoint_b string	Certificate name for endpoint B. Example: RemotePeerCertName
psk string	Pre-shared key used when authentication method is PSK. Example: 12345678
psk_encrypted boolean	Indicates if the provided pre-shared key is already encrypted. Example: true
shared_p1_settings boolean	Indicate whether to use the shared Phase‑1 (IKE) settings of the device (typically for dynamic peers). Example: true
ipsec_tunnel_core object	Phase 1 (IKE) and Phase 2 (IPSec) settings, Dead Peer Detection (DPD), and NAT-T keep-alive configurations for the tunnel.
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect if the remote peer is no longer responsive.
enabled boolean	Indicates whether DPD is enabled. Default is true. Example: true
dpd_type string	Dead Peer Detection type. This can be one of these values: traffic — Default. Based on traffic activity. If no traffic is detected for a specified idle time, DPD messages are sent. timer — Sent at regular intervals, regardless of traffic. Example: traffic
idle_time integer	Amount of time (in seconds) before the peer is considered idle. Specify a number of seconds from 10-300. Default value is 30 Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
interval integer	For timer‑based Dead Peer Detection, message interval between checks. Example: 30
max_failures integer	For timer‑based Dead Peer Detection, number of consecutive failures before declaring the peer down. Example: 5
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
pfs_dh_group string	DH group used for Perfect Forward Secrecy in Phase 2. Example: DH-14
ipsec_proposals array	Array of IPSec Phase 2 proposals.
protocol string	Phase‑2 protocol; currently ESP is supported. Example: ESP
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 8. Example: 8
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
lifebyte integer	Maximum amount of data (in bytes) that you can be transmit through an IPSec Security Association (SA) before it expires and must rekey. Example: 0
authentication string	The hash algorithm used to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
local_remote_pairs array	Policy‑based tunnels only. Custom local and remote pairs that define address match and direction with optional NAT.
enabled boolean	Indicates whether the local-remote pair is active. Example: true
local_network string	Optional name for the local network associated with this policy pair. Example:
local_address string	Local network address (CIDR) included in the policy‑based pair. Example: 192.0.2.0/24
remote_address string	Remote network address (CIDR) included in the policy‑based pair. Example: 192.0.2.0/24
direction string	Traffic direction for the policy pair. This can be: Inbound (`in`) Outbound (`out`) Bidirectional (`bi`) Example: in
dnat_ip string	Specifies an optional destination NAT. Example: 192.0.2.1
nat_base string	Specifies the source network for NAT. Must be in IPv4 CIDR format. Example: 192.0.2.0/24

Example Request

This request updates a BOVPN IPSec tunnel by name.

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/tunnels
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXIn0.eyJzdWIiOiN0LTJfa3hXeFdfU650heiAaUAy7XmiqbA'
-d '{
"version": 1,
"name": "MyName",
"endpoint_a": "MyEndA",
"endpoint_b": "MyEndB",
"endpoint_b_name": "MyEndBname",
"disabled": false,
"vpn_type": "route-based",
"address_family": 4,
"auth_method": "psk",
"interfaces": [
	{
	"endpoint_a": {
		"network": "MyNetA",
		"ip_address": "192.0.2.1",
		"id": {
			"type": "ip",
			"value": "MyValueA"
		},
		"perpetual_resolve": true
	},
	"endpoint_b": {
		"network": "MyNetB",
		"ip_address": "192.0.2.1",
		"id": {
			"type": "ip",
			"value": "MyValueB"
		},
		"perpetual_resolve": true
	},
	"df_bit": "copy",
	"pmtu_minimum": 1550,
	"pmtu_age": 2147483647
	}
],
"routes": {
	"endpoint_a": {
		"local_networks": [
		{
			"network": "MyLocANet",
			"metric": 1,
			"nat_base": "192.0.2.0/24",
			"dnat_ip": "192.0.2.1"
		}
	],
	"local_routes": [
		{
		"route": "192.0.2.0/24",
		"metric": 1,
		"nat_base": "192.0.2.0/24",
		"dnat_ip": "192.0.2.1"
		}
	]
},
"endpoint_b": {
	"local_networks": [
		{
		"network": "MyLocBNet",
		"metric": 1,
		"nat_base": "192.0.2.0/24",
		"dnat_ip": "192.0.2.1"
		}
	],
	"local_routes": [
		{
		"route": "192.0.2.0/24",
		"metric": 1,
		"nat_base": "192.0.2.0/24",
		"dnat_ip": "192.0.2.1"
		}
	]
	}
},
"vif": {
	"endpoint_a": {
		"vif_dev_name": "MyVifA",
		"vif_local_ip": "192.0.2.0/24",
		"vif_remote_ip": "192.0.2.0/24",
		"vif_mtu": 9000,
		"vif_df_bit": "copy"
		},
	"endpoint_b": {
		"vif_dev_name": "MyVifB",
		"vif_local_ip": "192.0.2.0/24",
		"vif_remote_ip": "192.0.2.0/24",
		"vif_mtu": 9000,
		"vif_df_bit": "copy"
		}
		},
	"certs": {
		"endpoint_a": "DeviceCertificateName",
		"endpoint_b": "RemotePeerCertName"
	},
	"psk": "stringst",
	"psk_encrypted": true,
	"shared_p1_settings": false,
	"ipsec_tunnel_core": {
		"natt_interval": 20,
		"dpd": {
		"enabled": true,
		"dpd_type": "traffic",
		"idle_time": 30,
		"retries": 5,
		"interval": 30,
		"max_failures": 5
		},
	"ike_proposals": [
		{
		"encryption": "AES-CBC-256",
		"authentication": "SHA2-256",
		"dh_group": "DH-14",
		"lifetime": 24,
		"lifetime_unit": "hours"
		}
	],
	"pfs_dh_group": "DH-14",
	"ipsec_proposals": [
		{
		"protocol": "ESP",
		"encryption": "AES-CBC-256",
		"authentication": "SHA2-256",
		"lifetime": 8,
		"lifetime_unit": "hours",
		"lifebyte": 0,
		"lifebyte_unit": "GB"
		}
	]
	},	
	"local_remote_pairs": [
		{
		"enabled": true,
		"local_network": "MyLocNetP",
		"local_address": "192.0.2.0/24",
		"remote_address": "192.0.2.0/24",
		"direction": "in",
		"dnat_ip": "192.0.2.1",
		"nat_base": "192.0.2.0/24"
		}
	]
}'

Update a BOVPN IPSec tunnel by unique object ID

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

Make a request to this endpoint to update an existing BOVPN configuration by unique object ID.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

objectid
string
REQUIRED

Object ID of the BOVPN tunnel to edit.

Each BOVPN tunnel has a unique ID in WatchGuard Cloud, which appears in the URL of the BOVPN configuration page. For example, if the BOVPN configuration page URL is https://usa.cloud.watchguard.com/ss-tenant/services/ACC-1234567/fb/device/FB-12345/configuration/bovpn/tunnel/ipsgp_123456DH, the tunnel object ID is ipsgp_123456DH.

Example: ipsgp_123456DH

Request Body

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object returned. Example: ipsec_gatewaytemplate
version integer REQUIRED	Version number of the BOVPN. Example: 1
account string REQUIRED	Your WatchGuard Cloud account ID. You can view your `accountId` on the My Account page in WatchGuard Cloud. Example: WGC-1-123abc456 or ACC-1234567
name string REQUIRED	Human-readable name of the BOVPN tunnel. Example: PBoVPN1
endpoint_a string REQUIRED	Cloud-managed Firebox device ID for endpoint A.
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array REQUIRED	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a string	Network name/role for endpoint A. For example, External.
endpoint_b string	Remote endpoint details.
id object	Unique ID of the IPSec gateway.
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
psk string	Pre-shared key used when authentication method is PSK. Example: 12345678
ipsec_tunnel_core object	Phase 1 (IKE) and Phase 2 (IPSec) settings, Dead Peer Detection (DPD), and NAT-T keep-alive configurations for the tunnel.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
authentication string	The hash algorithm used to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
ipsec_proposals array	Array of IPSec Phase 2 proposals.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 8. Example: 8
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
lifebyte integer	Maximum amount of data (in bytes) that you can be transmit through an IPSec Security Association (SA) before it expires and must rekey. Example: 0
authentication string	The hash algorithm used to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
pfs_dh_group string	Diffie-Hellman (DH) group used for Perfect Forward Secrecy (PFS) in Phase 2 of the VPN tunnel. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect if the remote peer is no longer responsive.
dpd_type string	Dead Peer Detection type. This can be one of these values: traffic — Default. Based on traffic activity. If no traffic is detected for a specified idle time, DPD messages are sent. timer — Sent at regular intervals, regardless of traffic. Example: traffic
idle_time integer	Amount of time (in seconds) before the peer is considered idle. Specifies a number of seconds from 10-300. Default value is 30 Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specifies a number from 1-30. Default value is 5. Example: 5
routes object REQUIRED	Routes to establish through the tunnel.
endpoint_a object	Route object for the device.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.1.0/24
endpoint_b object	Route object for the device that `endpoint_a` connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 6
route string	Route to establish through the tunnel. Example: 192.168.100.0/24
vif object	Virtual interface configuration for each VPN endpoint.
endpoint_a object	Route object for the device.
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 10.10.10.10/32
endpoint_b object	Route object for the device that `endpoint_a` connects to.
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 10.10.10.10/32
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 9.9.9.9/32

Example Request

This request updates a BOVPN IPSec tunnel by object ID.

curl -X PATCH 
https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/{accountid}/bovpn/ipsec/tunnels/ipsgp_123456DH
-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 '{
"id": "ipsgp_123456DH",
"object": "ipsec_gatewaypair",
"version": 1,
"account": "WGC-1-123abc456",
"name": "PBoVPN1",
"endpoint_a": "136162",
"endpoint_b_name": "CentralVPNServer",
"vpn_type": "route-based",
"address_family": 4,
"interfaces": [
	{
	"endpoint_a": {
		"network": "External"
		},
	"endpoint_b": {
		"id": {
			"type": "ip",
			"value": "192.88.99.200"
			}
		}
	}
],
"psk": "12345678",
"ipsec_tunnel_core": {
	"ike_proposals": [
		{
		"encryption": "AES-CBC-256",
		"dh_group": "DH-14",
		"lifetime": 24,
		"authentication": "SHA2-256"
		}
],
	"ipsec_proposals": [
		{
		"encryption": "AES-CBC-256",
		"lifetime": 8,
		"lifebyte": 0,
		"authentication": "SHA2-256"
		}
	],
"pfs_dh_group": "DH-14",
"natt_interval": 20,
"dpd": {
	"dpd_type": "traffic",
	"idle_time": 20,
	"retries": 5
	}
},
"routes": {
	"endpoint_a": {
		"local_routes": [
			{
			"metric": 1,
			"route": "192.168.1.0/24"
			}
		]
	},
	"endpoint_b": {
		"local_routes": [
			{
			"metric": 6,
			"route": "192.168.100.0/24"
			}
		]
	}
},
"vif": {
	"endpoint_a": {
		"vif_df_bit": "set",
		"vif_local_ip": "9.9.9.9/32",
		"vif_mtu": 1399,
		"vif_remote_ip": "10.10.10.10/32"
		},
	"endpoint_b": {
		"vif_local_ip": "10.10.10.10/32",
		"vif_remote_ip": "9.9.9.9/32"
		}
	}
}'

Example Response

This response includes the update to a BOVPN tunnel by Object ID in JSON format:

{
"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaypair",
"version": 2,
"account": "WGC-1-123abc456",
"created": 1579909960,
"author": "testuser",
"name": "PBoVPN1",
"endpoint_a": "136162",
"endpoint_b_name": "CentralVPNServer",
"vpn_type": "route-based",
"address_family": 4,
"interfaces": [
	{
	"endpoint_a": {
		"network": "External"
		},
	"endpoint_b": {
		"id": {
			"type": "ip",
			"value": "192.88.99.200"
			}
		}
	}
],
"psk": "12345678",
"ipsec_tunnel_core": {
	"ike_proposals": [
		{
		"encryption": "AES-CBC-256",
		"dh_group": "DH-14",
		"lifetime": 24,
		"authentication": "SHA2-256"
		}
	],
	"ipsec_proposals": [
		{
		"encryption": "AES-CBC-256",
		"lifetime": 8,
		"lifebyte": 0,
		"authentication": "SHA2-256"
		}
	],
	"pfs_dh_group": "DH-14",
	"natt_interval": 20,
	"dpd": {
		"dpd_type": "traffic",
		"idle_time": 20,
		"retries": 5
		}
	},
"routes": {
	"endpoint_a": {
		"local_routes": [
			{
			"metric": 1,
			"route": "192.168.1.0/24"
			}
		]
	},
	"endpoint_b": {
		"local_routes": [
			{
			"metric": 6,
			"route": "192.168.100.0/24"
			}
		]
	}
},
"vif": {
	"endpoint_a": {
		"vif_df_bit": "set",
		"vif_local_ip": "9.9.9.9/32",
		"vif_mtu": 1399,
		"vif_remote_ip": "10.10.10.10/32"
		},
	"endpoint_b": {
		"vif_local_ip": "10.10.10.10/32",
		"vif_remote_ip": "9.9.9.9/32"
		}
	}
}

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

id string	Identifier object for endpoint B. Example: ipsgp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object returned. Example: ipsec_gatewaytemplate
version integer	Version number of the BOVPN. Example: 2
account string	WatchGuard Cloud account ID associated with the object. Example: WGC-1-123abc456
created integer	Unix time stamp when the object was created. Example: 1579909960
author string	Author of the gateway pair. Always empty for objects added or updated with the Firebox Management API. Example: YourName
name string	Human-readable name of the BOVPN tunnel. Example: PBoVPN1
endpoint_a string	Endpoint A interface block. Example: 136162
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Endpoint A interface block.
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
endpoint_b object	Endpoint B interface block.
id object	Identifier object for endpoint B.
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
psk string	Pre-shared key used when authentication method is PSK. Example: 12345678
ipsec_tunnel_core object	Core settings for IKE (Phase 1) and IPSec (Phase 2), including DPD and NAT-T.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specifies the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
ipsec_proposals array	Array of IPSec Phase 2 proposals.
encryption string	Encryption algorithm. Example: AES-CBC-256
lifetime integer	Lifetime of the security association. Specifies the number of hours or minutes. The minimum value is 1, and the default value is 8. Example: 8
lifebyte integer	Data volume before Phase 2 SA rekey (0 disables byte lifetime). Example: 0
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
pfs_dh_group string	DH group used for Perfect Forward Secrecy in Phase 2. Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specifies a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect an unresponsive peer. Example:
dpd_type string	DPD trigger type (traffic or timer). Example: traffic
idle_time integer	Idle time in seconds before peer is considered idle. Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
routes object	Routing configuration for endpoint A and endpoint B. Example:
endpoint_a object	Endpoint A interface block. Example:
local_routes array	Array of local routes available through the VPN from the endpoint. Example:
metric integer	Route priority metric (lower value = higher priority). Example: 1
route string	CIDR-formatted route. Example: 192.168.1.0/24
endpoint_b object	Endpoint B interface block. Example:
local_routes array	Array of local routes available through the VPN from the endpoint. Example:
metric integer	Route priority metric (lower value = higher priority). Example: 6
route string	CIDR-formatted route. Example: 192.168.100.0/24
vif object	Virtual Interface settings for each endpoint in a route-based VPN. Example:
endpoint_a object	Endpoint A interface block. Example:
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local VIF IP address (CIDR). Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	Remote VIF IP address (CIDR). Example: 10.10.10.10/32
endpoint_b object	Endpoint B interface block. Example:
vif_local_ip string	Local VIF IP address (CIDR). Example: 10.10.10.10/32
vif_remote_ip string	Remote VIF IP address (CIDR). Example: 9.9.9.9/32

Modify Routes and Certificates

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

Make a request to this endpoint to update the routes list or certificate of a specific BOVPN IPSec tunnel by name or unique object ID.

Update the routes list or certificate of a specific BOVPN tunnel

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/

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 view your accountId on the My Account page in WatchGuard Cloud.

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

Request Body

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
name string	Name for the gateway pair. Example: PBoVPN1
routes object	Routes to establish through the tunnel.
endpoint_a object	Route object for the cloud-managed Firebox.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.0.1.0/24
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 2
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.0.2.0/24
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (endpoint_a) connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 6
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.168.100.0/24
certs object	Object of certificate references.
endpoint_a string REQUIRED	Certificate name for endpoint A. Example: cert_12345_ABCDEFGHIJKLMNOP
routes object	Routes to establish through the tunnel.
endpoint_a object	Route object for the cloud-managed Firebox.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 10.0.1.0/24
endpoint_b object	Route object for the Firebox.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 5
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 10.0.2.0/24
certs object	Object of certificate references.
endpoint_a string	Certificate name for endpoint A. Example: cert_12345_ABCDEFGHIJKLMNOP
endpoint_b string	Certificate name for endpoint B. Example: cert_67890_QRSTUVWXZABCDEF

Example Request

This request modifies the routes and certificates for a BOVPN tunnel.

curl -X PATCH https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/{accountid}/bovpn/ipsec/tunnels/
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ZslxmhXj7_h6T9PyN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'
-d '{
"update_routes": {
	"summary": "Update routes for both endpoints",
	"value": {
	"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
	"name": "PBoVPN1",
	"routes": {
		"endpoint_a": {
			"local_routes": [
					{
					"metric": 1,
					"route": "192.168.1.0/24"
					},
					{
					"metric": 2,
					"route": "192.168.2.0/24"
					}
				]
			},
		"endpoint_b": {
			"local_routes": [
					{
					"metric": 6,
					"route": "192.168.100.0/24"
					}
				]
			}
		}
		}
	},
"update_certificate": {
	"summary": "Update certificate for endpoint_a",
	"value": {
		"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
		"name": "PBoVPN1",
		"certs": {
			"endpoint_a": "cert_12345_ABCDEFGHIJKLMNOP"
			}
		}
		},
"update_routes_and_certificate": {
	"summary": "Update name, routes, and certificate",
	"value": {
		"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
		"name": "UpdatedTunnelName",
		"routes": {
			"endpoint_a": {
			"local_routes": [
					{
					"metric": 1,
					"route": "10.0.1.0/24"
					}
				]
			},
			"endpoint_b": {
			"local_routes": [
					{
					"metric": 5,
					"route": "10.0.2.0/24"
					}
				]
			}
		},
	"certs": {
		"endpoint_a": "cert_12345_ABCDEFGHIJKLMNOP",
		"endpoint_b": "cert_67890_QRSTUVWXZABCDEF"
		}
	}
}
}

Update the routes list or certificate of a specific BOVPN tunnel by Object ID

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

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 view your accountId on the My Account page in WatchGuard Cloud.

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

objectid
string
REQUIRED

Object ID of the BOVPN tunnel to edit.

Example: ipsgp_123456DH

Request Body

When you send a request to this endpoint, you can include theses parameters in the request body:

routes object	Routes to establish through the tunnel.
endpoint_a object	Route object for the cloud-managed Firebox.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.0.1.0/24
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 2
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.0.2.0/24
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (endpoint_a) connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 6
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 192.168.100.0/24
certs object	Object of certificate references.
endpoint_a string REQUIRED	Certificate name for endpoint A. Example: cert_12345_ABCDEFGHIJKLMNOP
routes object	Routes to establish through the tunnel.
endpoint_a object	Route object for the cloud-managed Firebox.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 10.0.1.0/24
endpoint_b object	Route object for the Firebox.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 5
route string	Specifies the local network that the VPN endpoint advertises or use as part of the tunnel Example: 10.0.2.0/24
certs object	Object of certificate references.
endpoint_a string	Certificate name for endpoint A. Example: cert_12345_ABCDEFGHIJKLMNOP
endpoint_b string	Certificate name for endpoint B. Example: cert_67890_QRSTUVWXZABCDEF

Example Request

This request modifies the routes and certificates for a BOVPN tunnel.

curl -X PATCH 
https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/{accountid}/bovpn/ipsec/tunnels/ipsgp_123456DH
-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 '{
"update_routes": {
	"summary": "Update routes for both endpoints",
	"value": {
		"routes": {
			"endpoint_a": {
				"local_routes": [
						{
					"metric": 1,
					"route": "192.168.1.0/24"
						},
						{
					"metric": 2,
					"route": "192.168.2.0/24"
						}
						]
					},
			"endpoint_b": {
				"local_routes": [
						{
					"metric": 6,
					"route": "192.168.100.0/24"
						}
					]
				}
			}
		}
	},
"update_certificate": {
	"summary": "Update certificate for endpoint_a",
	"value": {
	"certs": {
		"endpoint_a": "cert_12345_ABCDEFGHIJKLMNOP"
		}
	}
},
"update_routes_and_certificate": {
	"summary": "Update both routes and certificate",
	"value": {
	"routes": {
		"endpoint_a": {
			local_routes": [
				{
				"metric": 1,
				"route": "10.0.1.0/24"
				}
			]
		},
		"endpoint_b": {
			"local_routes": [
				{
				"metric": 5,
				"route": "10.0.2.0/24"
				}
			]
		}
},
"certs": {
	"endpoint_a": "cert_12345_ABCDEFGHIJKLMNOP",
	"endpoint_b": "cert_67890_QRSTUVWXZABCDEF"
		}
		}
	}
}

Example Response

This response includes routes and certificate references for a specific BOVPN IPSec tunnel in JSON format:

{
"id": "string",
"object": "string",
"version": 1,
"account": "WGC-1-123abc456",
"created": 1579907960,
"author": "string",
"name": "string",
"endpoint_a": "string",
"endpoint_b": "string",
"endpoint_b_name": "string",
"disabled": false,
"vpn_type": "route-based",
"address_family": 4,
"auth_method": "psk",
"interfaces": [
	{
	"endpoint_a": {
		"network": "string",
		"ip_address": "192.0.2.1",
		"id": {
			"type": "ip",
			"value": "string"
			},
		"perpetual_resolve": true
		},
	"endpoint_b": {
		"network": "string",
		"ip_address": "192.0.2.1",
		"id": {
			"type": "ip",
			"value": "string"
			},
	"perpetual_resolve": true
	},
	"df_bit": "copy",
	"pmtu_minimum": 1550,
	"pmtu_age": 2147483647
	}
],
"routes": {
	"endpoint_a": {
		"local_networks": [
		{
			"network": "string",
			"metric": 1,
			"nat_base": "192.0.2.0/24",
			"dnat_ip": "192.0.2.1"
			}
		],
		"local_routes": [
			{
			"route": "192.0.2.0/24",
			"metric": 1,
			"nat_base": "192.0.2.0/24",
			"dnat_ip": "192.0.2.1"
			}
		]
	},
	"endpoint_b": {
		"local_networks": [
			{
			"network": "string",
			"metric": 1,
			"nat_base": "192.0.2.0/24",
			"dnat_ip": "192.0.2.1"
			}
		],
		"local_routes": [
			{
			"route": "192.0.2.0/24",
			"metric": 1,
			"nat_base": "192.0.2.0/24",
			"dnat_ip": "192.0.2.1"
			}
		]
	}
},
"vif": {
	"endpoint_a": {
		"vif_dev_name": "string",
		"vif_local_ip": "192.0.2.0/24",
		"vif_remote_ip": "192.0.2.0/24",
		"vif_mtu": 9000,
		"vif_df_bit": "copy"
		},
	"endpoint_b": {
		"vif_dev_name": "string",
		"vif_local_ip": "192.0.2.0/24",
		"vif_remote_ip": "192.0.2.0/24",
		"vif_mtu": 9000,
		"vif_df_bit": "copy"
		}
	},
"certs": {
	"endpoint_a": "DeviceCertificateName",
	"endpoint_b": "RemotePeerCertName"
},
"psk": "stringst",
"psk_encrypted": true,
"shared_p1_settings": false,
"ipsec_tunnel_core": {
		"natt_interval": 20,
		"dpd": {
			"enabled": true,
			"dpd_type": "traffic",
			"idle_time": 30,
			"retries": 5,
			"interval": 30,
			"max_failures": 5
		},
	"ike_proposals": [
			{
			"encryption": "AES-CBC-256",
			"authentication": "SHA2-256",
			"dh_group": "DH-14",
			"lifetime": 24,
			"lifetime_unit": "hours"
			}
		],
	"pfs_dh_group": "DH-14",
	"ipsec_proposals": [
			{
			"protocol": "ESP",
			"encryption": "AES-CBC-256",
			"authentication": "SHA2-256",
			"lifetime": 8,
			"lifetime_unit": "hours",
			"lifebyte": 0,
			"lifebyte_unit": "GB"
			}
		]
	},
	"local_remote_pairs": [
			{
			"enabled": true,
			"local_network": "string",
			"local_address": "192.0.2.0/24",
			"remote_address": "192.0.2.0/24",
			"direction": "in",
			"dnat_ip": "192.0.2.1",
			"nat_base": "192.0.2.0/24"
			}
		]
	}
}

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object.
version integer	Version number of the BOVPN. Example: 1
account string	WatchGuard Cloud account ID.
created integer	Unix time stamp when the object was created.
author string	Author of the gateway pair. Always empty for objects added or updated with the Firebox Management API.
name string	Name of the IPSec gateway pair.
endpoint_a string	ID of endpoint A.
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Defines the cloud-managed Firebox interface settings.
network string	Network definition for the tunnel. This can be one of these values: External Trusted Optional Example: External
endpoint_b object	Identifies the remote device or endpoint that the cloud-managed Firebox (`endpoint_a`) connects to.
id object	Unique ID for the IPSec gateway.
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Specifies the identifier string (IP address, FQDN, user FQDN, or X.500 Distinguished Name). Depends on `type`. Example: 192.88.99.200
psk string	Pre-shared key (PSK) used for authentication between endpoints. Example: 24681012
ipsec_tunnel_core object	Phase 1 (IKE) and Phase 2 (IPSec) settings, Dead Peer Detection (DPD), and NAT-T keep-alive configurations for the tunnel.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
ipsec_proposals array	Array of IPSec Phase 2 proposals.
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
pfs_dh_group string	Diffie-Hellman (DH) group used for Perfect Forward Secrecy (PFS) in Phase 2 of the VPN tunnel. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings used to detect if the remote peer is no longer responsive.
dpd_type string	Dead Peer Detection type. This can be one of these values: traffic — Default. Based on traffic activity. If no traffic is detected for a specified idle time, DPD messages are sent. timer — Sent at regular intervals, regardless of traffic. Example: traffic
idle_time integer	Amount of time (in seconds) before the peer is considered idle. Specify a number of seconds from 10-300. Default value is 30 Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
routes object	Routes to establish through the tunnel.
endpoint_a object	Route object for the device.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 1
route string	Route to establish through the tunnel. Example: 192.168.1.0/24
endpoint_b object	Route object for the device that `endpoint_a` connects to.
local_routes array	Array of routes available through the VPN from the local endpoint.
metric integer	Specifies route priority. Lower values have higher priority. Default is 1. Example: 6
route string	Route to establish through the tunnel. Example: 192.168.100.0/24
certs object	Object of certificate references.
endpoint_a string	Certificate name for endpoint A. Example: DeviceCertificateName
endpoint_b string	Certificate name for endpoint B. Example: RemotePeerCertName
vif object	Virtual interface configuration for each VPN endpoint.
endpoint_a object	Route object for the cloud-managed Firebox.
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 10.10.10.10/32
endpoint_b object	Route object for the remote device or endpoint that the cloud-managed Firebox (`endpoint_a`) connects to.
vif_local_ip string	Local IP address for the virtual interface used in the route-based VPN. Example: 10.10.10.10/32
vif_remote_ip string	IP address of the virtual interface in a route-based VPN tunnel. Example: 9.9.9.9/32

Delete a BOVPN Tunnel

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

Make a request to this endpoint to delete a BOVPN IPSec tunnel by name or by object ID.

Delete a BOVPN tunnel by name

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels

Make a request to this endpoint to delete a BOVPN tunnel by name.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

name
string
REQUIRED

Name for the gateway pair.

Example: PBoVPN1

Example Request

This request deletes a BOVPN tunnel by name.

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/tunnels/tunnels?name=PBoVPN1
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'	
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'	
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0._h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiqbA'

Example Response

The response returns the deleted BOVPN in JSON format:

{
"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaypair",
"version": 1,
"account": "WGC-1-123abc456",
"created": 1579907960,
"author": "testuser",
"name": "PBoVPN1",
"endpoint_a": "136162",
"endpoint_b_name": "CentralVPNServer",
"vpn_type": "route-based",
"address_family": 4,
"interfaces": [
	{
	"endpoint_a": {
		"network": "External"
		},
	"endpoint_b": {
		"id": {
			"type": "ip",
			"value": "192.88.99.200"
			}
		}
	}
],
"psk": "12345678",
"ipsec_tunnel_core": {
	"ike_proposals": [
			{
		"encryption": "AES-CBC-256",
		"dh_group": "DH-14",
		"lifetime": 24,
		"authentication": "SHA2-256"
		}
	],
	"ipsec_proposals": [
		{
		"encryption": "AES-CBC-256",
		"lifetime": 8,
		"lifebyte": 0,
		"authentication": "SHA2-256"
		}
	],
	"pfs_dh_group": "DH-14",
	"natt_interval": 20,
	"dpd": {
		"dpd_type": "traffic",
		"idle_time": 20,
		"retries": 5
		}
},
"routes": {
	"endpoint_a": {
		"local_routes": [
			{
			"metric": 1,
			"route": "192.168.1.0/24"
			}
		]
	},
	"endpoint_b": {
		"local_routes": [
			{
			"metric": 6,
			"route": "192.168.100.0/24"
			}
		]
	}
},
"vif": {
	"endpoint_a": {
		"vif_df_bit": "set",
		"vif_local_ip": "9.9.9.9/32",
		"vif_mtu": 1399,
		"vif_remote_ip": "10.10.10.10/32"
		},
	"endpoint_b": {
		"vif_local_ip": "10.10.10.10/32",
		"vif_remote_ip": "9.9.9.9/32"
		}
	}
}

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object, typically ipsec_gatewaypair.
version integer	Version number of the BOVPN.
account string	WatchGuard Cloud account ID.
created integer	Unix time stamp when the object was created. Example: 1579909960
author string	Author of the gateway pair. Always empty for objects added or updated with the Firebox Management API.
name string	Name of the IPSec gateway pair.
endpoint_a string	ID of endpoint A.
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Configuration for endpoint A. Example:
network string	Network ID for endpoint A. Example: External
endpoint_b object	Configuration for endpoint B. Example:
id object	Peer gateway identifier object. Example:
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Peer gateway identifier value (IP or FQDN). Example: 192.88.99.200
psk string	Pre-shared key used for authentication. Example: 12345678
routes object	Routing configuration for both endpoints. Example:
local_routes array	Local routes for endpoint. Example:
route string	CIDR-formatted route for endpoint. Example: 192.168.1.0/24
metric integer	Route metric for endpoint. Example: 1
ipsec_tunnel_core object	Core IPSec tunnel configuration.
ike_proposals array	IKE Phase 1 proposals. Example:
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
lifebyte integer	Phase 2 byte lifetime (0 disables). Example: 0
pfs_dh_group string	Diffie-Hellman group for Perfect Forward Secrecy. Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings. Example:
dpd_type string	Dead Peer Detection type (traffic or timer). Example: traffic
idle_time integer	Idle time before DPD triggers. Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
vif object	Virtual interface configuration for endpoints. Example:
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local VIF IP for endpoint. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	Remote VIF IP for endpoint. Example: 10.10.10.10/32

Delete a BOVPN tunnel by Object ID

/{v1}/configuration/{accountid}/bovpn/ipsec/tunnels/{objectid}

Make a request to this endpoint to delete a BOVPN tunnel by object ID.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

objectid
string
REQUIRED

Each BOVPN tunnel has a unique ID in WatchGuard Cloud, which appears in the URL of the BOVPN configuration page.

Example: When the BOVPN configuration page URL is https://usa.cloud.watchguard.com/ss-tenant/services/ACC-1234567/fb/device/FB-12345/configuration/bovpn/tunnel/ipsgp_123456DH, the tunnel ID is ipsgp_123456DH.

Example Request

This request deletes a BOVPN tunnel by object ID.

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/tunnels/ipsgp_123456DH
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'	
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'	
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhoSmEza0ltcEFMbnluT05DcFdIT2tZPSIsImFsZyI6IlJTMjU2In0._h6T9PyqjLxLjFEq5S6oK9u4IVDVBlRxbURaRVAGb7ywfHiZEPDgceV-Wnv0AIhDzj5dL28AmiqbA'

Example Response

The response returns the deleted BOVPN in JSON format:

{
"id": "ipsgp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaypair",
"version": 1,
"account": "WGC-1-123abc456",
"created": 1579907960,
"author": "testuser",
"name": "PBoVPN1",
"endpoint_a": "136162",
"endpoint_b_name": "CentralVPNServer",
"vpn_type": "route-based",
"address_family": 4,
"interfaces": [
	{
	"endpoint_a": {
		"network": "External"
		},
	"endpoint_b": {
		"id": {
			"type": "ip",
			"value": "192.88.99.200"
			}
		}
	}
],
"psk": "12345678",
"ipsec_tunnel_core": {
	"ike_proposals": [
			{
		"encryption": "AES-CBC-256",
		"dh_group": "DH-14",
		"lifetime": 24,
		"authentication": "SHA2-256"
		}
	],
	"ipsec_proposals": [
		{
		"encryption": "AES-CBC-256",
		"lifetime": 8,
		"lifebyte": 0,
		"authentication": "SHA2-256"
		}
	],
	"pfs_dh_group": "DH-14",
	"natt_interval": 20,
	"dpd": {
		"dpd_type": "traffic",
		"idle_time": 20,
		"retries": 5
		}
},
"routes": {
	"endpoint_a": {
		"local_routes": [
			{
			"metric": 1,
			"route": "192.168.1.0/24"
			}
		]
	},
	"endpoint_b": {
		"local_routes": [
			{
			"metric": 6,
			"route": "192.168.100.0/24"
			}
		]
	}
},
"vif": {
	"endpoint_a": {
		"vif_df_bit": "set",
		"vif_local_ip": "9.9.9.9/32",
		"vif_mtu": 1399,
		"vif_remote_ip": "10.10.10.10/32"
		},
	"endpoint_b": {
		"vif_local_ip": "10.10.10.10/32",
		"vif_remote_ip": "9.9.9.9/32"
		}
	}
}

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object, typically ipsec_gatewaypair.
version integer	Version number of the BOVPN.
account string	WatchGuard Cloud account ID.
created integer	Unix time stamp when the object was created. Example: 1579909960
author string	Author of the gateway pair. Always empty for objects added or updated with the Firebox Management API.
name string	Name of the IPSec gateway pair.
endpoint_a string	ID of endpoint A.
endpoint_b_name string	Name of the second Firebox. Example: CentralVPNServer
vpn_type string	VPN IPSec tunnel type. Must be either route‑based or policy‑based. Default is `route-based`. Example: route-based
address_family integer	IP address family for all gateway endpoints. Default is `4`. This can be one of these values: 4 (IPv4) 6 (IPv6) Example: 4
interfaces array	Array of interface endpoint mappings between endpoint A and endpoint B.
endpoint_a object	Configuration for endpoint A. Example:
network string	Network ID for endpoint A. Example: External
endpoint_b object	Configuration for endpoint B. Example:
id object	Peer gateway identifier object. Example:
type string	Gateway endpoint ID type. Default is `ip`. This can be one of these values: ip — An address. fqdn — A fully qualified domain name. ufqdn — A user fully qualified domain name. x500_name — An X.500 distinguished name. Example: ip
value string	Peer gateway identifier value (IP or FQDN). Example: 192.88.99.200
psk string	Pre-shared key used for authentication. Example: 12345678
routes object	Routing configuration for both endpoints. Example:
local_routes array	Local routes for endpoint. Example:
route string	CIDR-formatted route for endpoint. Example: 192.168.1.0/24
metric integer	Route metric for endpoint. Example: 1
ipsec_tunnel_core object	Core IPSec tunnel configuration.
ike_proposals array	IKE Phase 1 proposals. Example:
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-CBC-256
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-256
dh_group string	Diffie-Hellman group. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
lifebyte integer	Phase 2 byte lifetime (0 disables). Example: 0
pfs_dh_group string	Diffie-Hellman group for Perfect Forward Secrecy. Example: DH-14
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20
dpd object	Dead Peer Detection settings. Example:
dpd_type string	Dead Peer Detection type (traffic or timer). Example: traffic
idle_time integer	Idle time before DPD triggers. Example: 20
retries integer	Number of retries to make before the peer is considered unreachable. Specify a number from 1-30. Default value is 5. Example: 5
vif object	Virtual interface configuration for endpoints. Example:
vif_df_bit string	Specifies the DF bit value. This can be one of these values: copy — Copies the DF (Don't Fragment) bit from the original packet. set — Sets the DF bit to 1 (prevent fragmentation). clear — Clears the DF bit (allow fragmentation). Example: set
vif_local_ip string	Local VIF IP for endpoint. Example: 9.9.9.9/32
vif_mtu integer	Maximum packet size (in bytes) that can be transmitted through the virtual interface without fragmentation. Can be an integer between 68 and 9000. Example: 1500
vif_remote_ip string	Remote VIF IP for endpoint. Example: 10.10.10.10/32

Manage Shared Phase 1 Settings

/{v1}/configuration/{accountid}/bovpn/ipsec/p1_shared_settings

The BOVPN tunnel uses a shared Phase 1 configuration when the remote gateway endpoint is dynamic. You manage this configuration separately from individual tunnels, and the configuration applies to all BOVPN tunnels on the Firebox that connect to remote endpoints with dynamic IP addresses.

Get Shared Phase 1 Settings

/{v1}/configuration/{accountid}/bovpn/ipsec/p1_shared_settings

Make a request to this endpoint to get the BOVPN IPSec Phase‑1 (P1) shared settings object(s) for an account or 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 view 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
string
integer

Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page.

The device ID can be a string or an integer for a standalone device. 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 or 12345.

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

Example: FB-12345

Example Request

This request returns the BOVPN IPSec P1 shared settings for a device:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/p1_shared_settings?device=12345
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE5mM2FXTHhl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response returns the object that represents the shared P1 settings for the device or all devices, in JSON format:

{
"id": "ipstp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaytemplate",
"version": 1,
"account": "ACC-1234567",
"created": 1579907960,
"device": "12345",
"author": "testuser",
"ike_proposals": [
	{
	"encryption": "AES-GCM-256",
	"authentication": "SHA2-512",
	"dh_group": "DH-21",
	"lifetime": 8
	}
	],
	"natt_interval": 20
}

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object. Example: ipsec_gatewaytemplate
version integer	Version number of the BOVPN. Example: 1
account string	WatchGuard Cloud account ID. Example: WGC-1-123abc456
created integer	Unix time stamp when the object was created. Example: 1579907960
device string	Firebox device ID. Example: 12345
author string	Author of the gateway pair. Always empty for objects added or updated with the Firebox Management API.
ike_proposals array	Array of IKE proposals.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-GCM-256
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-512
dh_group string	Diffie-Hellman (DH) group used with the IKE key exchange process. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20

Create Shared Phase 1 Settings

/{v1}/configuration/{accountid}/bovpn/ipsec/p1_shared_settings

Make a request to this endpoint to create a shared P1 settings object. One object can exist for each Firebox. The Firebox ID is specified in the device attribute of the configuration 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 view your accountId on the My Account page in WatchGuard Cloud.

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

Request Body

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

device string integer	Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. The device ID can be a string or an integer for a standalone device. 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 or 12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: FB-12345
ike_proposals array REQUIRED	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-GCM-256
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-512
dh_group string	Diffie-Hellman (DH) group used with the IKE key exchange process. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the lifetime value. This can be one of these values: hours (Default) minutes Example: hours
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20

Example Request

This request creates an IKEv2 shared settings object:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/p1_shared_settings
	-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",
	"ike_proposals": [
	{
	"encryption":"AES-CBC-256",
	"dh_group":"DH-14",
	"lifetime":24,
	"lifetime_unit":"hours",
	"authentication":"SHA2-256"
	}
	],
	"natt_interval":20
}'

Example Response

The response represents the BOVPN IPSec P1 shared settings object for a Firebox in JSON format:


{
"id": "ipstp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaytemplate",
"version": 1,
"account": "WGC-1-123abc456",
"created": 1579907960,
"device": "12345",
"author": "testuser",
"ike_proposals": [
	{
	"encryption": "AES-CBC-256",
	"authentication": "SHA2-256",
	"dh_group": "DH-14",
	"lifetime": 24,
	"lifetime_unit": "hours"
	}
	],
}
"natt_interval": 20
}'

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object. Example: ipsec_gatewaytemplate
version integer	Version number of the BOVPN. Example: 1
account string	WatchGuard Cloud account ID. Example: WGC-1-123abc456
created integer	Unix time stamp when the object was created. Example: 1579907960
device string	Firebox device ID. Example: 12345
author string	Author of the gateway pair. Always empty for objects added or updated with the Firebox Management API.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-GCM-256
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-512
dh_group string	Diffie-Hellman (DH) group used with the IKE key exchange process. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20

Update Shared Phase 1 Settings

/{v1}/configuration/{accountid}/bovpn/ipsec/p1_shared_settings

Make a request to this endpoint to update the specified BOVPN IPSec P1 shared settings object for the device. The Firebox ID is specified in the device attribute of the configuration 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 view your accountId on the My Account page in WatchGuard Cloud.

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

Request Body

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object. Example: ipsec_gatewaytemplate
version integer REQUIRED	Version number of the BOVPN. Example: 1
account string	WatchGuard Cloud account ID. Example: WGC-1-123abc456
device string	Firebox device ID. Example: 12345
ike_proposals array REQUIRED	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-GCM-256
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-512
dh_group string	Diffie-Hellman (DH) group used with the IKE key exchange process. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20

Example Request

This request updates the specified BOVPN IPSec P1 shared settings object for a device.

curl -X PUT https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/bovpn/ipsec/p1_shared_settings
	-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 '{
"id": "ipstp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaytemplate",
"version": 1,
"account": "WGC-1-123abc456",
"device": "12345",
"ike_proposals": [
	{
	"encryption": "AES-GCM-256",
	"authentication": "SHA2-512",
	"dh_group": "DH-20",
	"lifetime": 16
	}
	],
"natt_interval": 20
}'

Example Response

The response represents the BOVPN IPSec P1 shared settings object for a Firebox in JSON format:

{
"id": "ipstp_12345_ARBHLJ70Y78rGOIGBS",
"object": "ipsec_gatewaytemplate",
"version": 1,
"account": "WGC-1-123abc456",
"created": 1579907960,
"device": "12345",
"author": "testuser",
"ike_proposals": [
	{
	"encryption": "AES-CBC-256",
	"authentication": "SHA2-256",
	"dh_group": "DH-14",
	"lifetime": 24,
	"lifetime_unit": "hours"
	}
	],
}
"natt_interval": 20
}'

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

id string	Unique ID of the IPSec gateway. Example: ipstp_12345_ARBHLJ70Y78rGOIGBS
object string	Type of object. Example: ipsec_gatewaytemplate
version integer	Version number of the BOVPN. Example: 1
account string	WatchGuard Cloud account ID. Example: WGC-1-123abc456
created integer	Unix time stamp when the object was created. Example: 1579907960
device string	Firebox device ID. Example: 12345
author string	Author of the gateway pair. Always empty for objects added or updated with the Firebox Management API.
ike_proposals array	Array of IKE Phase 1 proposals that define encryption and authentication settings for tunnel negotiation.
encryption string	Encryption algorithm. This can be one of these values: AES-CBC-128 AES-CBC-192 AES-CBC-256 (Default) AES-GCM-128 AES-GCM-192 AES-GCM-256 Example: AES-GCM-256
authentication string	The hash algorithm to use to verify message integrity and authenticity. This can be one of these values: SHA2-256 (Default) SHA2-384 SHA2-512 Example: SHA2-512
dh_group string	Diffie-Hellman (DH) group used with the IKE key exchange process. This can be one of these values: DH-14 (Default) DH-15 DH-19 DH-20 DH-21 Example: DH-14
lifetime integer	Lifetime of the security association. Specify the number of hours or minutes. The minimum value is 1, and the default value is 24. Example: 24
lifetime_unit string	Specifies the time unit for the `lifetime` value. This can be one of these values: hours (Default) minutes Example: hours
natt_interval integer	Keep-alive interval (in seconds). Specify a number of seconds from 1 through 65535. The default value is 20. Example: 20

Certificates for Cloud-Managed Fireboxes

You can manage your account certificates and Firebox certificates for cloud-managed devices in WatchGuard Cloud. For more information, go to Manage Certificates in WatchGuard Cloud.

Certificate operations work only with cloud‑managed Fireboxes that store configuration in WatchGuard Cloud. They do not work with locally‑managed Fireboxes, including those with WatchGuard Cloud reporting, because these devices store no configuration in WatchGuard Cloud. The API returns an empty response for locally‑managed Fireboxes.

You can use the Firebox Certificate Management API to:

Create a Certificate
Install a Certificate
Delete a Certificate
Get Certificates

Endpoints:

/{v1}/configuration/{accountid}/system/certificates

/{v1}/command/{accountid}/system/certificates/install

/{v1}/configuration/{accountid}/system/certificates/{objectid}

/{v1}/configuration/{accountid}/system/certificates

/{v1}/configuration/{accountid}/system/certificates/{objectid}

Create a Certificate

/{v1}/configuration/{accountid}/system/certificates

Make a request to this endpoint to create a certificate for a WatchGuard Cloud account or for a specific device. Certificates must be in Base64 PEM encoded format or PFX file format.

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 view your accountId on the My Account page in WatchGuard Cloud.

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

Request Body

The information you must provide in the request body depends on the type of certificate configuration you want to add:

Add an account-level certificate to a WatchGuard Cloud account

name string REQUIRED	Name of the certificate. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: AccountCert
description string	Optional text description of the certificate. You can use the description to identify the purpose of the certificate. Example: My Account Certificate
pem string	Certificate content in PEM format. Includes the public certificate block. Example: "-----BEGIN CERTIFICATE-----......-----END CERTIFICATE-----"
pvt_key string	Private key associated with the certificate, in PEM format. Required for certificates that use private/public key pairs. Account-level certificates are in PEM format. Example: -----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASC...\n-----END PRIVATE

Example Request

This request adds an account-level certificate to a WatchGuard Cloud account.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/system/certificates
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJjYjhVTzJlelpWaGZzVnZnYhGni-J2eJvbTn9ZwaRSAb9XT2CgVZX61UwZ9pQoMGpe4z620W56VOxQuxrTgjqGYHj5-K2oDCWhRWV7BANnUar6vguyGO4_M99Aht4kJlDZp482uMnY79ziK60_LRrnBPi6jPBalHVVfUOeykN_BT9foEDbO1-CTTGj-MC19ltkEX4gfODa9lqXw8lSzQ-SfXFHoCfFOflzYjXUQ_iAAL7lfw1WU31tAepmAa2YZ7M1LTOtIuP5ckHCqghlYNXafQ'
	-d '{
	"name": "AccountCert",
	"description": "", 
	"pem": "PEM String",
	"pvt_key": "Private Key String"
	}'

Add a device-level PEM certificate to a Firebox in a WatchGuard Cloud account

device string integer REQUIRED	Required when you create or install device-level certificates. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. The device ID of a standalone device can be a string or an integer. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is 12345 or FB-12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: FB-12345
name string REQUIRED	Name of the certificate. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: AccountCert
description string	Optional text description of the certificate. You can use the description to identify the purpose of the certificate. Example: My Account Certificate
pem string REQUIRED	Certificate content in PEM format. Includes the public certificate block. Example: -----BEGIN CERTIFICATE-----......-----END CERTIFICATE-----
pvt_key string REQUIRED	Private key associated with the certificate, in PEM format. Required for certificates that use private/public key pairs. Account-level certificates are in PEM format. Example: -----BEGIN PRIVATE KEY-----\nMIIEvQIBADEFAASC...\n-----END PRIVATE

Example Request

This request adds a device-level PEM certificate to a Firebox in a WatchGuard Cloud account.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/system/certificates
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJjYjhVTzJlelpWaGZzVnZnYhGni-J2eJvbTn9ZwaRSAb9XT2CgVZX61UwZ9pQoMGpe4z620W56VOxQuxrTgjqGYHj5-K2oDCWhRWV7BANnUar6vguyGO4_M99Aht4kJlDZp482uMnY79ziK60_LRrnBPi6jPBalHVVfUOeykN_BT9foEDbO1-CTTGj-MC19ltkEX4gfODa9lqXw8lSzQ-SfXFHoCfFOflzYjXUQ_iAAL7lfw1WU31tAepmAa2YZ7M1LTOtIuP5ckHCqghlYNXafQ'
	-d '{
	"device": "12345",
	"name": "DeviceCert",
	"description": "", 
	"pem": "PEM String",
	"pvt_key": "Private Key String"
	}'

Add a certificate with a password-protected .PFX file to a Firebox in a WatchGuard Cloud account

device string integer REQUIRED	Required when you create or install device-level certificates. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. The device ID of a standalone device can be a string or an integer. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is 12345 or FB-12345. For FireClusters, specify the full device ID. For example, FBCL-12345. Example: FB-12345
name string REQUIRED	Name of the certificate. This can include only letters, numbers, spaces, parentheses "()", asterisks "*", periods ".", hyphens "-", and underscores "_". Maximum: 58 characters. Example: AccountCert
description string	Optional text description of the certificate. You can use the description to identify the purpose of the certificate. Example: My Account Certificate
pfx string REQUIRED	Certificate in .PFX format. Example: -----BEGIN PKCS12-----\nMIIG...==\n-----END PKCS12-----
password string REQUIRED	Password used to decrypt the .PFX file, if applicable. Required when the certificate is provided in PFX format and is encrypted. Example: M!cr0S3cur3#2025!

Example Request

This request adds a certificate with a password-protected .PFX file to a Firebox in a WatchGuard Cloud account.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/system/certificates
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJjYjhVTzJlelpWaGZzVnZnYhGni-J2eJvbTn9ZwaRSAb9XT2CgVZX61UwZ9pQoMGpe4z620W56VOxQuxrTgjqGYHj5-K2oDCWhRWV7BANnUar6vguyGO4_M99Aht4kJlDZp482uMnY79ziK60_LRrnBPi6jPBalHVVfUOeykN_BT9foEDbO1-CTTGj-MC19ltkEX4gfODa9lqXw8lSzQ-SfXFHoCfFOflzYjXUQ_iAAL7lfw1WU31tAepmAa2YZ7M1LTOtIuP5ckHCqghlYNXafQ'
	-d '{
	"device": "12345",
	"name": "MyDeviceCert", 
	"description": "",
	"pfx": "PFX String",
	"password": "Password for PFX decryption."
	}

Use an alias to add an existing account-level certificate to a Firebox in a WatchGuard Cloud account

alias
string
REQUIRED

User-defined name of an existing account-level certificate that was previously created or imported into your WatchGuard Cloud account. You can use GET/v1/configuration/{accountid}/system/certificates to return all account‑level certificates and aliases.
Example: YourAccountCert

device
string
integer
REQUIRED

Required when you create or install device-level certificates. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. The device ID of a standalone device can be a string or an integer.
For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is 12345 or FB-12345.

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

Example: FB-12345

Example Request

This request uses an alias to add an existing account-level certificate to a Firebox in a WatchGuard Cloud account.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/system/certificates
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJjYjhVTzJlelpWaGZzVnZnYhGni-J2eJvbTn9ZwaRSAb9XT2CgVZX61UwZ9pQoMGpe4z620W56VOxQuxrTgjqGYHj5-K2oDCWhRWV7BANnUar6vguyGO4_M99Aht4kJlDZp482uMnY79ziK60_LRrnBPi6jPBalHVVfUOeykN_BT9foEDbO1-CTTGj-MC19ltkEX4gfODa9lqXw8lSzQ-SfXFHoCfFOflzYjXUQ_iAAL7lfw1WU31tAepmAa2YZ7M1LTOtIuP5ckHCqghlYNXafQ'
	-d '{
	"alias": "YourAccountCert",
	"device": "12345"
	}'

Example Response

The response returns the certificate object in JSON format:

{
"account": "ACC-1234567",
"id": "crt_34425_jf3904ukdj94",
"device": "FB-12345",
"name": "DeviceCert",
"algorithm": "RSA",
"cert_type": "web_server",
"cert_fingerprint": "aa:aa:aa:aa:aa:aa:aa:aa",
"valid_from": 1738863038,
"expiration": 1815016892,
"key_length": 2048,
"signature_algo": "sha256WithRSAEncryption",
"key_usage": [
	"digital_signature",
	"content_commitment",
	"key_encipherment"
	],
"extended_key_usage": [
	"serverAuth"
	],
"issuer": "o=WatchGuard cn=WatchGuard Certificate Authority",
"subject": "o=myCompany cn=mydevice.org",
"subject_alt": [
	"mydevicealt.org"
	],
"pem": "-----BEGIN CERTIFICATE-----\nMIID...==\n-----END CERTIFICATE-----"
}

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

account string	WatchGuard Cloud account ID associated with the certificate.
id string	Unique identifier for the certificate object.
device string	Firebox device ID the certificate is associated with.
name string	Name of the certificate.
algorithm string	Algorithm used to generate the certificate.
cert_type string	Type of certificate.
cert_fingerprint string	Fingerprint of the certificate.
valid_from integer	Start of the certificate validity period (Unix time stamp).
expiration integer	End of the certificate validity period (Unix time stamp).
key_length integer	Length of the key in bits.
signature_algo string	Signature algorithm used.
key_usage array	List of key usage purposes.
extended_key_usage array	List of extended key usage purposes.
issuer string	Issuer of the certificate.
subject string	Subject of the certificate.
subject_alt array	Subject alternative names.
pem string	PEM-formatted public certificate string.

Install a Certificate to a Device

/{v1}/commands/{accountid}/system/certificates/install

Make a request to this endpoint to install a device-level certificate. You install a certificate to one or more Firebox devices so they can actively use it in the configuration.

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 view your accountId on the My Account page in WatchGuard Cloud.

For example: WGC-1-123abc456 or ACC-1234567

Request Body

The information you must provide in the request body depends on the type of certificate installation:

Install a certificate, referenced by name, to a Firebox in a WatchGuard Cloud account

certificate
string
REQUIRED

Name of the certificate. The certificate must already be added to the Firebox.
Example: MyDeviceWebCert

device
string
integer
REQUIRED

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

Example: FB-12345

Example Request

This request installs a certificate, referenced by name, to a specific Firebox in a WatchGuard Cloud account.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/ACC-1234567/system/certificates/install
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJjYjhVTzJlelpWaGZzVnZnYhGni-J2eJvbTn9ZwaRSAb9XT2CgVZX61UwZ9pQoMGpe4z620W56VOxQuxrTgjqGYHj5-K2oDCWhRWV7BANnUar6vguyGO4_M99Aht4kJlDZp482uMnY79ziK60_LRrnBPi6jPBalHVVfUOeykN_BT9foEDbO1-CTTGj-MC19ltkEX4gfODa9lqXw8lSzQ-SfXFHoCfFOflzYjXUQ_iAAL7lfw1WU31tAepmAa2YZ7M1LTOtIuP5ckHCqghlYNXafQ'
	-d '{
	"certificate": "DeviceCert",
	"device": "12345"
	}'

Install a certificate, referenced by ID, to multiple Fireboxes in a WatchGuard Cloud account

certificate_id
string
REQUIRED

Unique identifier for the certificate. Make a GET request to the /{v1}/configuration/{accountid}/system/certificates endpoint to retrieve the certificate_id. Used when you reference the certificate in API calls or when you update or delete it. The certificate must have already been added to the Firebox.
Example: crt_45979_jf390cvdsert

devices
array
REQUIRED

Device IDs of the devices on which to install the certificate, separated by commas.

Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. The device ID of a standalone device can be a string or an integer. For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID can be 12345 or FB-12345.
For FireClusters, specify the full device ID. For example, FBCL-12345.

Example: 12345, 67890, 54321

Example Request

This request installs a certificate, referenced by ID, to multiple Fireboxes in a WatchGuard Cloud account.

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/commands/ACC-1234567/system/certificates/install
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJjYjhVTzJlelpWaGZzVnZnYhGni-J2eJvbTn9ZwaRSAb9XT2CgVZX61UwZ9pQoMGpe4z620W56VOxQuxrTgjqGYHj5-K2oDCWhRWV7BANnUar6vguyGO4_M99Aht4kJlDZp482uMnY79ziK60_LRrnBPi6jPBalHVVfUOeykN_BT9foEDbO1-CTTGj-MC19ltkEX4gfODa9lqXw8lSzQ-SfXFHoCfFOflzYjXUQ_iAAL7lfw1WU31tAepmAa2YZ7M1LTOtIuP5ckHCqghlYNXafQ'
	-d '{
	"certificate_id": "crt_45979_jf390cvdsert",
	"devices": [ 
	"12345",
	"67890",
	"54321"
	 ]
	}'

Example Response

The response returns details of the installed certificate in JSON format:

{
"account": "ACC-123456",
"children": [],
"confirmed_date": null,
"created": "2025-08-21T18:38:40Z",
"created_epoch": 1755520,
"data": "{\"xpath_request\": {\"version\": 1, \"transaction\": 
...
	    \"purpose\": \"ca\"}], \"final_cert\": true}",
"device": [12345],
"folder": null,
"group": null,
"id": "install_cert_123456rFa",
"job_id": null,
"model": "FireboxV-SM",
"name": "FireboxV_SM_J",
"operator": null,
"os_version": "12.11.3.B719894",
"parent": null,
"serial": "FVE1234567",
"start_date": "2025-08-21T18:38:40Z",
"start_date_epoch": 1751234520,
"status": "in_progress",
"template_initiated": false,
"timeout": 900,
"timeout_epoch": 1751234520,
"ttl": 175123420,
"type": "install_cert",
"version": null
}

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

account string	WatchGuard Cloud account ID.
children array	List of child objects.
confirmed_date string	Date when the action was confirmed.
created string	Creation time of the certificate.
created_epoch integer	Creation time in Unix epoch format.
data object	Associated data payload.
device string	Firebox device ID.
folder string	Folder name or path.
group string	Group identifier.
id string	Unique object ID.
job_id string	Job identifier for tracking.
model string	Device model name.
name string	Name of the object.
operator string	Operator who initiated the action.
os_version string	Operating system version.
parent string	Parent object reference.
serial string	Device serial number.
start_date string	Start date of the operation.
start_date_epoch integer	Start date in Unix epoch format.
status string	Current status of the operation.
template_initiated boolean	Indicates if initiated from a template.
timeout string	Timeout duration.
timeout_epoch integer	Timeout in Unix epoch format.
ttl integer	Time to live value.
type string	Type of the object.
version string	Version information.

Delete a Certificate

/{v1}/configuration/{accountid}/system/certificates/{objectid}

Make a request to this endpoint to delete a certificate from a WatchGuard Cloud account.

When you delete a certificate, you can no longer use the certificate for authentication. If you delete an automatically-generated certificate, your Firebox creates a new self-signed certificate with the same purpose the next time it reboots.

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 view your accountId on the My Account page in WatchGuard Cloud.

For example: WGC-1-123abc456 or ACC-1234567

objectid
string
REQUIRED

Unique identifier for a certificate. Used when you reference the certificate in API calls or when you update or delete it.
To get the objectid, make a request to:
GET /v1/configuration/{accountid}/system/certificates

Example: crt_88910_ynqLebq5lcvnBUG

Example Request

This example deletes a certificate:

curl -X DELETE https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-12345687/system/certificates/crt_88910_ynqLebq5lcvnBUG
	-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 returns details of the deleted certificate in JSON format:

{
"account": "ACC-1234567",	
"akid": "BA:B3:71:40:5B:3B:24:4E:3C:C3:B3:9E:55:2D",
"algorithm": "EC",
"alias": "ACC-1234567/crt_tlb4t1pq4kKxc",
"author": "",
"author_username": "",
"cert_fingerprint": "56:81:7A:3B:BA:E0:23:59:AA:19:AA:F5:3B",
"cert_type": "ca",
"created": 1753387567,
"device": "12345",
"expiration": 1997604396,
"id": "crt_88910_ynqLlcvnBUG",
"inactive": true,
"inception_time": 1753387269,
"issuer": "c=cn st=sc l=cdc o=wg ou=vpn cn=jlh [email protected]",
"key_length": "256",
"key_usage": [
	"digital_signature",
	"key_cert_sign",
	"crl_sign"
	],
"metadata": {
	"tags": [
		"ca"
		]
	},
"name": "EC CA cert",
"object": "certificate",
"original_author": "7a6tuM0ax5FES2Q==",
"original_author_username": "TechP",
"pem": "-----BEGIN CERTIFICATE-----\nMIICStBO9pVwIhAOhO....MLppC70lXhjP8B\n-----END CERTIFICATE-----\n\n",
"pubkey_fingerprint": "CC:88:97:AC:B1:9B:33:08:AF",
"referencedby": [],
"references": [
	"ACC-1234567/crt_tlb4eC0t1pq4kKxc"
		],
"signature_algo": "ecdsa-with-SHA512",
"skid": "BA:B3:71:40:5B:3B:56:2E:93:C3:B3:9E:55:2D",
"subject": "c=cn st=sc l=cdc o=wg ou=vpn cn=jlh [email protected]",
"subject_name_fingerprint": "880A8123456BE775032F4",
"valid_from": 1682244396,
"version": 2
}

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

account string	Your WatchGuard Cloud account ID.
akid string	Authority Key Identifier.
algorithm string	Algorithm used to generate the certificate.
alias string	The name of an account certificate object.
author string	Author of the object. Always empty for objects added or updated with the Firebox Management API.
author_username string	User name of the author.
cert_fingerprint string	Fingerprint of the certificate.
cert_type string	Type of certificate.
created integer	Time that the object was created, specified in Unix epoch time format.
device string	WatchGuard Cloud Firebox device ID.
expiration integer	Unix epoch time when the certificate expires.
id string	Unique ID that identifies this object.
inactive boolean	Indicates whether the certificate is inactive.
inception_time integer	Unix epoch time when the certificate becomes valid.
issuer string	Issuer of the certificate.
key_length string	Length of the key.
key_usage array[string]	Key usages.
metadata object	Metadata associated with the certificate.
name string	Name of the certificate.
object string	Type of object.
original_author string	Original author of the object.
original_author_username string	User name of the original author.
pem string	PEM-encoded certificate string.
pubkey_fingerprint string	Fingerprint of the public key.
referencedby array[string]	Objects that reference this certificate.
references array[string]	References to this certificate.
signature_algo string	Signature algorithm used.
skid string	Subject Key Identifier.
subject string	Subject of the certificate.
subject_name_fingerprint string	Fingerprint of the subject name.
valid_from integer	Unix epoch time when the certificate becomes valid.
version integer	Version number of the certificate.

Get Certificates

/{v1}/configuration/{accountid}/system/certificates

/{v1}/configuration/{accountid}/system/certificates/{objectid}

Make a request to this endpoint to get certificates from a Firebox or WatchGuard Cloud account.

The information you must provide in the request depends on which certificates you want to retrieve:

Get all certificates from a WatchGuard Cloud account

Path Parameters

accountid
string
REQUIRED

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

For example: WGC-1-123abc456 or ACC-1234567

Example Request

This request gets all certificates from a WatchGuard Cloud account.

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/system/certificates
	-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 returns the retrieved certificate in JSON format:

{
"account": "WGC-1-123abc456",
"id": "crt_34425_jf3904ukdj94",
"device": "FB-123456",
"name": "MyDeviceWebCert",
"algorithm": "RSA",
"cert_type": "web_server",
"cert_fingerprint": "aa:aa:aa:aa:aa:aa:aa:aa",
"valid_from": 1738863038,
"expiration": 1815016892,
"key_length": 2048,
"signature_algo": "sha256WithRSAEncryption",
"key_usage": [
	"digital_signature",
	"content_commitment",
	"key_encipherment"
],
"extended_key_usage": [
	"serverAuth"
],
"issuer": "o=WatchGuard cn=WatchGuard Certificate Authority",
"subject": "o=myCompany cn=mydevice.org",
"subject_alt": [
	"mydevicealt.org"
	],
"pem": "pem_string"
}

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

account string	Your WatchGuard Cloud account ID.
id string	Unique ID that identifies this object.
device string	WatchGuard Cloud Firebox device ID.
name string	Name of the certificate.
algorithm string	Algorithm used to generate the certificate.
cert_type string	Type of certificate.
cert_fingerprint string	Fingerprint of the certificate.
valid_from integer	Unix epoch time when the certificate becomes valid.
expiration integer	Unix epoch time when the certificate expires.
key_length string	Length of the key.
signature_algo string	Signature algorithm used.
key_usage array[string]	Key usage information.
extended_key_usage array[string]	Extended key usages.
issuer string	Issuer of the certificate.
subject string	Subject of the certificate.
subject_alt string	Alternate subject of the certificate.
pem string	PEM-encoded certificate string.

Get all certificates from a specific Firebox in a WatchGuard Cloud account

Path Parameters

accountid
string
REQUIRED

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

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

Request Parameters

device
string
integer
REQUIRED

Required when creating or installing device-level certificates. Each device has a unique ID in WatchGuard Cloud, which appears in the URL of the Device Summary page. The device ID of a standalone device can be a string or an integer.
For example, if the Device Summary page URL is https://usa.cloud.watchguard.com/services/fb/device/FB-12345/summary, the device ID is 12345 or FB-12345.

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

Example: FB-12345

Example Request

This request gets all certificates from a specific Firebox.

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/ACC-1234567/system/certificates?device=12345
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabk...8AmiGIkWtWinF0UD-NSMKN4vtszK2sUWUSl8ZfVNGU650heiAaUAy7XmiqbA'

Example Response

The response returns the retrieved certificate in JSON format:

{
"account": "WGC-1-123abc456",
"id": "crt_34425_jf3904ukdj94",
"device": "FB-123456",
"name": "MyDeviceWebCert",
"algorithm": "RSA",
"cert_type": "web_server",
"cert_fingerprint": "aa:aa:aa:aa:aa:aa:aa:aa",
"valid_from": 1738863038,
"expiration": 1815016892,
"key_length": 2048,
"signature_algo": "sha256WithRSAEncryption",
"key_usage": [
	"digital_signature",
	"content_commitment",
	"key_encipherment"
],
"extended_key_usage": [
	"serverAuth"
],
"issuer": "o=WatchGuard cn=WatchGuard Certificate Authority",
"subject": "o=myCompany cn=mydevice.org",
"subject_alt": [
	"mydevicealt.org"
	],
"pem": "pem_string"
}

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

account string	Your WatchGuard Cloud account ID.
id string	Unique ID that identifies this object.
device string	WatchGuard Cloud Firebox device ID.
name string	Name of the certificate.
algorithm string	Algorithm used to generate the certificate.
cert_type string	Type of certificate.
cert_fingerprint string	Fingerprint of the certificate.
valid_from integer	Unix epoch time when the certificate becomes valid.
expiration integer	Unix epoch time when the certificate expires.
key_length string	Length of the key.
signature_algo string	Signature algorithm used.
key_usage array[string]	Key usage information.
extended_key_usage array[string]	Extended key usages.
issuer string	Issuer of the certificate.
subject string	Subject of the certificate.
subject_alt string	Alternate subject of the certificate.
pem string	PEM-encoded certificate string.

Get a specific certificate from a WatchGuard Cloud account

Path Parameters

accountid
string
REQUIRED

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

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

objectid
string
REQUIRED

Example: crt_88910_ynqLebq5lcvnBUG

Example Request

This response gets a specific certificate from a WatchGuard Cloud account.

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/system/certificates/crt_88910_ynqLebq5lcvn
	-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 returns the retrieved certificate in JSON format:

{
"account": "WGC-1-123abc456",
"id": "crt_34425_jf3904ukdj94",
"device": "FB-123456",
"name": "MyDeviceWebCert",
"algorithm": "RSA",
"cert_type": "web_server",
"cert_fingerprint": "aa:aa:aa:aa:aa:aa:aa:aa",
"valid_from": 1738863038,
"expiration": 1815016892,
"key_length": 2048,
"signature_algo": "sha256WithRSAEncryption",
"key_usage": [
	"digital_signature",
	"content_commitment",
	"key_encipherment"
],
"extended_key_usage": [
	"serverAuth"
],
"issuer": "o=WatchGuard cn=WatchGuard Certificate Authority",
"subject": "o=myCompany cn=mydevice.org",
"subject_alt": [
	"mydevicealt.org"
	],
"pem": "pem_string"
}

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

account string	Your WatchGuard Cloud account ID.
id string	Unique ID that identifies this object.
device string	WatchGuard Cloud Firebox device ID.
name string	Name of the certificate.
algorithm string	Algorithm used to generate the certificate.
cert_type string	Type of certificate.
cert_fingerprint string	Fingerprint of the certificate.
valid_from integer	Unix epoch time when the certificate becomes valid.
expiration integer	Unix epoch time when the certificate expires.
key_length string	Length of the key.
signature_algo string	Signature algorithm used.
key_usage array[string]	Key usage information.
extended_key_usage array[string]	Extended key usages.
issuer string	Issuer of the certificate.
subject string	Subject of the certificate.
subject_alt string	Alternate subject of the certificate.
pem string	PEM-encoded certificate string.

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.