# Device

A device is the basic unit that most of Firewalla's feature set, including monitoring, alarms, and traffic filtering, is built with. Each device represents either a physical device, a network interface, or a VPN client.

# Get Devices

GET https://msp_domain/v2/devices

Parameters

Name	Value
Authorization required	Personal access token

Name	Value
box	Gets devices under a specific Firewalla box, must be supplied with the ID of a box
group	Gets devices under a specific Firewalla box group, must be supplied with the ID of a box group

Response

200 Success

A JSON array of Devices

[
  {
    "id": "AA:BB:CC:DD:EE:FF",
    "macVendor": "Apple Inc.",
    "gid": "00000000-0000-0000-0000-000000000000",
    "ip": "192.168.120.1",
    "ipReserved": true,
    "name": "My Iphone",
    "online": true,
    "lastSeen": "1647832113.571",
    "network": {
      "name": "Home Office",
      "id": "00000000-1111-1111-1111-000000000000"
    },
    "group": {
      "name": "Kid",
      "id": "15"
    },
    "totalDownload": 45185926,
    "totalUpload": 55977001,
  }
]

401 Permission Denied

Examples

const axios = require('axios');

// Change these three configurations to what you need
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "YOUR_PERSONAL_ACCESS_TOKEN";

axios({
    method: 'get',
    url: `https://${msp_domain}/v2/devices`,
    headers: {
        Authorization: `Token ${token}`
    }
}).then((res) => {
    let data = res.data;
    console.log(data);
})

curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]'

# Get a list of device names
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' | jq '.[].name'

# Get all devices with a reserved IP
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' \
| jq '.[] | select(.ipReserved == true) | "\(.name), \(.ip), \(.id), Reserved:\(.ipReserved)"'

# Get a list of group names
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' \
| jq 'unique_by(.group.name) | .[] | .group.name | select (. != null)'

# Get a list of devices belong to a group
curl --request GET  \
--url 'https://[msp_domain]/v2/devices' \
--header 'Authorization: Token [your_personal_access_token]' \
| jq '.[] | select (.group.name == "testGroup1")'

# Update Device MSP 2.9.0 or later

PATCH https://msp_domain/v2/boxes/:gid/devices/:id

Note

Currently, only the name field can be modified. Any other field in the request body is ignored.

Parameters

Name	Value
Authorization required	Personal access token
Content-Type	application/json

Name	Value
gid required	The ID of the Firewalla box
id required	The ID of the device to update

Name	Type	Description
name	string	The new name for the device (max 32 characters)

Response

200 Success

Returns the updated Device object.

{
  "id": "AA:BB:CC:DD:EE:FF",
  "macVendor": "Apple Inc.",
  "gid": "00000000-0000-0000-0000-000000000000",
  "ip": "192.168.120.1",
  "ipReserved": true,
  "name": "Updated Device Name",
  "online": true,
  "lastSeen": "1647832113.571",
  "network": {
    "name": "Home Office",
    "id": "00000000-1111-1111-1111-000000000000"
  },
  "group": {
    "name": "Kid",
    "id": "15"
  },
  "totalDownload": 45185926,
  "totalUpload": 55977001
}

400 Bad Request

Returns when the name is empty or exceeds 32 characters.

404 Not Found

Returns when the device is not found.

401 Permission Denied

Examples

const axios = require('axios');

// Change these three configurations to what you need
const msp_domain = process.env.msp_domain || "mydomain.firewalla.net";
const token = process.env.token || "YOUR_PERSONAL_ACCESS_TOKEN";
const boxId = "00000000-0000-0000-0000-000000000000";
const deviceId = "AA:BB:CC:DD:EE:FF";

axios({
    method: 'patch',
    url: `https://${msp_domain}/v2/boxes/${boxId}/devices/${deviceId}`,
    headers: {
        Authorization: `Token ${token}`,
        'Content-Type': 'application/json'
    },
    data: {
        name: "My Updated Device"
    }
}).then((res) => {
    let data = res.data;
    console.log(data);
}).catch((error) => {
    console.error('Error:', error.response?.data || error.message);
})

curl --request PATCH \
--url 'https://[msp_domain]/v2/boxes/[box_id]/devices/[device_id]' \
--header 'Authorization: Token [your_personal_access_token]' \
--header 'Content-Type: application/json' \
--data '{"name": "My Updated Device"}'

# Update device name with validation
curl --request PATCH \
--url 'https://[msp_domain]/v2/boxes/[box_id]/devices/[device_id]' \
--header 'Authorization: Token [your_personal_access_token]' \
--header 'Content-Type: application/json' \
--data '{"name": "New Device Name"}' | jq '.name'