Firebox Add Device Management API

You can use the Firebox Add Device Management API to retrieve the available time zone values for a device, retrieve the device ID for a Firebox by serial number, and add an allocated Firebox to WatchGuard Cloud as a cloud-managed device. The device must already be activated and allocated to your WatchGuard Cloud account. When you add the device, the API marks it as cloud-managed, initializes its configuration, configures the external interface and DNS, and deploys the initial configuration.

For more information about how to add a Firebox in the WatchGuard Cloud UI, go to Add a Firebox to WatchGuard Cloud.

You can use the Firebox Add Device Management API to:

Retrieve Available Time Zone Values
Retrieve the Device ID for a Firebox by Serial Number
Add a Firebox to WatchGuard Cloud

Endpoints:

/{v1}/configuration/{accountid}/devices/timezones

/{v1}/info/{accountid}/devices/sn/{serial_number}

/{v1}/configuration/{accountid}/devices/add

Retrieve Available Time Zone Values

/{v1}/configuration/{accountid}/devices/timezones

Make a request to this endpoint to retrieve the IANA time zone values accepted by the Firebox Add Device Management API.

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

Example Request

This request retrieves the available time zone values for the specified WatchGuard Cloud account:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/devices/timezones
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...'
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response returns the available IANA time zone values in JSON format:

[
    "America/Los_Angeles",
    "America/New_York",
    "UTC",
    "Europe/London"
]

Retrieve the Device ID for a Firebox by Serial Number

/{v1}/info/{accountid}/devices/sn/{serial_number}

Make a request to this endpoint to retrieve the Firebox device ID for the specified WatchGuard Cloud account using the serial number in serial_number.

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

serial_number
string
REQUIRED

Specifies the Firebox serial number. Dashes are allowed. Maximum: 64 characters.

Example: VOODOO-SN-007

Example Request

This request retrieves the device ID for the Firebox with serial number VOODOO-SN-007:

curl -X GET https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/info/WGC-1-123abc456/devices/sn/VOODOO-SN-007
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...'
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'

Example Response

The response returns the device serial lookup object in JSON format:

{
    "account_id": "WGC-1-78faf1f596b248bdb644",
    "serial_number": "VOODOO-SN-007",
    "device_id": "59431",
    "short_model_name": "M300"
}

Data returned in the response includes the following parameters:

account_id string REQUIRED	Indicates the WatchGuard Cloud account ID that owns the device. Example: WGC-1-78faf1f596b248bdb644
serial_number string REQUIRED	Indicates the Firebox serial number. Example: VOODOO-SN-007
device_id string REQUIRED	Indicates the Firebox ID in WatchGuard Cloud. Example: 59431
short_model_name string REQUIRED	Indicates the Firebox model short name (for example, M300, T70). Example: M300

Add a Firebox to WatchGuard Cloud

/{v1}/configuration/{accountid}/devices/add

Make a request to this endpoint to add an allocated Firebox to WatchGuard Cloud as a cloud-managed device. You must activate and allocate the device to the account before you make this request. This operation marks the device as cloud-managed, initializes its configuration, configures the external interface and DNS, and deploys the initial 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 see 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 must include this information in the request body:

device string integer REQUIRED	Specifies the Firebox ID in WatchGuard Cloud. You must activate and allocate the device to the account before you make this request. Example: 131144
model string REQUIRED	Specifies the Firebox model name as reported by WatchGuard Cloud (for example, M300, T45-CW, T85-PoE, and Firebox NV5). Example: M300
name string	Specifies the friendly name for the device. Default is the serial-number-based name assigned during activation. Minimum: 1 character. Maximum: 58 characters. Example: seattle-office-fbx
timezone string	Specifies the IANA time zone identifier for the device. Default: America/Los_Angeles. Retrieve valid values from Retrieve Available Time Zone Values. Example: America/Los_Angeles
external_interface object REQUIRED	Specifies the configuration for the external interface. The allowed values for `connection_type` are: static dhcp pppoe
connection_type string REQUIRED	Specifies the external interface connection type. The allowed values are: static dhcp pppoe
ip_address string	Specifies the IPv4 address in CIDR notation for a static connection. Required when `connection_type` is static. Example: 20.0.2.1/24
gateway string	Specifies the IPv4 gateway address for a static connection. Required when `connection_type` is static. Example: 192.0.2.1
dhcp_client object	Specifies optional DHCP client settings when `connection_type` is dhcp.
ip_addr string	Specifies an optional IPv4 address for the DHCP client. Example: 192.0.2.1
client_id string	Specifies an optional DHCP client ID. Minimum: 1 character. Maximum: 255 characters.
host_name string	Specifies an optional DHCP host name. Minimum: 1 character. Maximum: 255 characters.
pppoe_client object	Specifies PPPoE client settings. Required when `connection_type` is pppoe.
ip_addr string	Specifies an optional IPv4 address for the PPPoE client. Example: 192.0.2.1
user string REQUIRED	Specifies the PPPoE user name. Minimum: 1 character. Maximum: 63 characters.
password string REQUIRED	Specifies the PPPoE password. Minimum: 1 character. Maximum: 192 characters.
dns_server string REQUIRED	Specifies the public DNS server IPv4 address for the device. Example: 192.0.2.1
admin_password string REQUIRED	Specifies the password for the device admin account. Minimum: 8 characters. Maximum: 32 characters.
status_password string REQUIRED	Specifies the password for the device status account. Minimum: 8 characters. Maximum: 32 characters.
staged boolean	Specifies whether to create a staged deployment for cloud-managed Fireboxes. When set to `true`, the endpoint creates a staged deployment that remains in WatchGuard Cloud and is not sent to the device. When set to `false`, the endpoint creates a full deployment and clears the staged state. If you omit this parameter, the initial deployment is staged. Default: `true`.

Example Request

This request adds an allocated Firebox to WatchGuard Cloud as a cloud-managed device with a static external interface:

curl -X POST https://api.usa.cloud.watchguard.com/rest/firebox/management/v1/configuration/WGC-1-123abc456/devices/add
	-H 'Authorization: Bearer eyJraWQiOiJNWnpabklNK2V6Q3BXUE...'
	-H 'Accept: application/json'
	-H 'Content-Type: application/json'
	-H 'WatchGuard-API-Key: s9t7El6RZFg8UcmRhYKdwXqBhyuioiWER83Nqd0tL'
	-d '{
    "device": "131144",
    "model": "M300",
    "name": "seattle-office-fbx",
    "timezone": "America/Los_Angeles",
    "external_interface": {
        "connection_type": "static",
        "ip_address": "20.0.2.1/24",
        "gateway": "192.0.2.1"
    },
    "dns_server": "192.0.2.1",
    "admin_password": "AdminPass1",
    "status_password": "StatusPass1",
    "staged": true
}'

Example Response

The response returns the device object in JSON format after the device is added as cloud-managed:

{
    "device": "131144",
    "model": "M300",
    "name": "seattle-office-fbx",
    "timezone": "America/Los_Angeles",
    "external_interface": {
        "connection_type": "static",
        "ip_address": "20.0.2.1/24",
        "gateway": "192.0.2.1"
    },
    "dns_server": "192.0.2.1",
    "agent_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "deployment": {
        "id": "dep_131144_abc123",
        "status": "pending",
        "description": "Initial configuration deployment"
    }
}

Data returned in the response includes the following parameters:

device string integer REQUIRED	Indicates the Firebox ID in WatchGuard Cloud. Example: 131144
model string REQUIRED	Provides the Firebox model name. Example: M300
name string REQUIRED	Provides the friendly name assigned to the device. Example: seattle-office-fbx
timezone string REQUIRED	Provides the IANA time zone applied to the device. Example: America/Los_Angeles
external_interface object REQUIRED	External interface configuration applied to the device.
dns_server string REQUIRED	Provides the public DNS server configured on the device. Example: 192.0.2.1
agent_token string REQUIRED	Provides a one-time agent token returned when the device is configured for cloud management. The Firebox uses this token to register with WatchGuard Cloud.
deployment object REQUIRED	Contains details of the initial configuration deployment.
id string	Unique ID that identifies this deployment. Example: dep_131144_abc123
status string	Indicates the current deployment status. Example: pending
description string	Provides the deployment description.
password_error string	Indicates that password setting failed after successful deployment. The device is functional, but the API did not set the passwords. Retry through the Commands API.