Skip to content

Retrieve groups

GET/firewall-groups

Firewall Management API · Firewall Groups

Retrieve firewall groups.

Required permissionfwcm.firewall.group:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
page query integer No The page number to fetch, starting with 1.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.
pageSize query integer No The size of the page requested.
recurseSubgroups query boolean No Whether to include nested child groups or not.
search query string No Search.
searchFields query string No Comma-separated fields to match. Valid fields are name, parentId.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/firewall/v1/firewall-groups" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/firewall/v1/firewall-groups",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/firewall/v1/firewall-groups" -Headers $headers


package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/firewall/v1/firewall-groups", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/firewall/v1/firewall-groups", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — Groups retrieved successfully.

Response fields

itemsarray of objectrequired
Items must be unique.
Firewall group.
Show child attributesHide child attributes
idstring (uuid)required
Group ID.
namestringrequired
Group name.
Must be 3–40 characters long.
parentGroupobject
Group ID.
Show child attributesHide child attributes
idstring (uuid)required
Group ID.
namestring
Group name.
Must be 1–250 characters long.
tenantobjectrequired
Tenant ID.
Show child attributesHide child attributes
idstring (uuid)required
Tenant ID.
lockedByManagingAccountbooleanrequired
Shows if the group is locked by managing account.
firewallsobjectrequired
Associated firewall IDs.
Show child attributesHide child attributes
totalintegerrequired
Number of firewalls in this firewall group.
itemsCountintegerrequired
Number of list items.
itemsarray of objectrequired
Items must be unique.
Firewall ID.
Show child attributesHide child attributes
idstring (uuid)required
Firewall ID.
configImportobject
Firewall group configuration import status.
Show child attributesHide child attributes
sourceFirewallobjectrequired
Firewall ID.
Show child attributesHide child attributes
idstring (uuid)required
Firewall ID.
percentCompleteintegerrequired
Group creation progress (percentage).
Must be ≥ 0 and ≤ 100.
statusstring (enum)required
Configuration import status.
Must be one of: success, initializing, initializingFailed, initializingFailedExport, uploaded, uploadFailed, downloadFailed, processing, failed.
errorsarray of object
Configuration import errors.
Show child attributesHide child attributes
entityNamestring (string)required
subEntityNamestring (string)
messagesarray of objectrequired
Error messages.
Show child attributesHide child attributes
codestring
Error code.
messagestring
Error message.
createdByobjectrequired
Show child attributesHide child attributes
idstring
Principal email or client ID.
typestring (enum)
Principal type.
Must be one of: user, service.
namestring
User principal name.
accountTypestringrequired
Account type.
Must be one of: partner, tenant.
accountIdstring (uuid)required
Account ID.
createdAtstring (date-time)required
updatedByobject
Show child attributesHide child attributes
idstring
Principal email or client ID.
typestring (enum)
Principal type.
Must be one of: user, service.
namestring
User principal name.
accountTypestringrequired
Account type.
Must be one of: partner, tenant.
accountIdstring (uuid)required
Account ID.
updatedAtstring (date-time)
pagesobjectrequired
Pagination information for the response object.
Show child attributesHide child attributes
currentintegerrequired
The 1-based page number being returned.
totalinteger
(Optional) The total number of pages that exist, if pageTotal=true in the request.
itemsinteger
(Optional) The total number of items across all pages, if pageTotal=true in the request.
sizeintegerrequired
The size of the page being returned.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
401 Authentication required.
403 Authorization required.
500 Unexpected error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "items": [
    {
      "id": "4f0ed382-ce28-4a9a-8a3d-f3d577ca7e72",
      "name": "UK Office",
      "parentGroup": {
        "id": "b88df1aa-1fc2-472b-983d-d77f5c96e525"
      },
      "tenant": {
        "id": "3e382b8e-49fd-4cd9-8360-a364371d7650"
      },
      "lockedByManagingAccount": false,
      "firewalls": {
        "total": 10,
        "itemsCount": 5,
        "items": [
          {
            "id": "df1f8ccf-1223-46ed-9042-6672a8326b8c"
          },
          {
            "id": "97483e58-55d7-44fb-b03f-9422f106ef66"
          },
          {
            "id": "7e5605c1-da16-4995-9679-767a8b79328d"
          },
          {
            "id": "8e5605c1-da16-4995-9679-767a8b79328d"
          },
          {
            "id": "4e5605c1-da16-4995-9679-767a8b79328d"
          }
        ]
      },
      "configImport": {
        "sourceFirewall": {
          "id": "902967e4-3df9-4dd0-8e23-1c917802b44c"
        },
        "percentComplete": 100,
        "status": "success",
        "errors": []
      },
      "createdBy": {
        "id": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "type": "user",
        "name": "example",
        "accountId": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "accountType": "customer"
      },
      "createdAt": "2022-03-30T05:43:59.492Z",
      "updatedBy": {
        "id": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "type": "user",
        "name": "example",
        "accountId": "97483e58-55d7-44fb-b03f-9422f106ef66",
        "accountType": "customer"
      },
      "updatedAt": "2022-03-30T05:43:59.492Z"
    }
  ],
  "pages": {
    "current": "1,",
    "total": "1,",
    "size": "100,",
    "maxSize": "100,",
    "items": 1
  }
}

See the guide for a narrative walkthrough of this API.