Getting started

Overview¶

The Switch Management API allows you to manage switch settings, create or update policies, and verify their status. See the product documentation.

Pre-requisites¶

You must have a set of API credentials (service principal) to be able to call the Switch Management API. For more information, refer to the appropriate quick-start guide:

Sophos Partners: Read the Partner Getting Started guide first.
Enterprise customers: If you use Sophos Fusion Enterprise to manage multiple tenants, read the Organization Getting Started guide first.
Other customers: Read the Tenant Getting Started guide first.

Making API requests¶

You can make the API calls in the folowing sections using curl. Follow the instructions on cURL's website to install this tool.

When using curl, a request to the Switch Management API has the following general form:

curl -X<method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The command includes the following placeholders:

<method>: The request method. For the switch management operation, this is either GET or PUT.
<tenant-id>: The ID of the tenant you want to query.
<jwt>: The JWT access token returned when the IDP authenticates the service principal.
<data-region>: The regional API host in the data region where the tenant data is located.
<path>: The request path for the API operation, for example, /switch/v1/settings/mac-filtering.

For brevity, the API descriptions in this guide only specify the request method and path. For example:

GET /switch/v1/settings/mac-filtering

To make an actual API request, you must expand this to the full form shown above.

All API requests return HTTP status code 200 or 201 when successful.

Terminology¶

Before you use the Switch Management API, here are a few terms you should know:

Switch: A hardware appliance that connects devices within a network and enables them to communicate with each other.
Task: Tasks help verify that configured policies are successfully applied to the switch.

Policy management¶

MAC filters¶

Get MAC filters¶

Call this API to get the MAC filter settings for the tenant.

GET /switch/v1/settings/mac-filtering

Response: This returns the MAC filter settings for the tenant. Here's an example:

{
    "tenant": {
        "id": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "createdBy": {
        "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
        "type": "service",
        "accountType": "tenant",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "createdAt": "2024-05-08T15:01:39.726373Z",
    "updatedBy": {
        "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
        "type": "service",
        "accountType": "tenant",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "updatedAt": "2024-05-08T15:01:39.732Z",
    "macAddresses": [
        "02:02:03:04:05:11",
        "02:02:04:05:06:20"
    ]
}

Update MAC filters¶

PUT /switch/v1/settings/mac-filtering

Note: You must enter the entire list of MAC addresses you want to block. This replaces the existing blocked list.

Request body:

{
    "macAddresses": [
        "02:02:03:04:07:50",
        "02:02:04:05:08:35"
    ]
}

Response:

{
    "tenant": {
        "id": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "createdBy": {
        "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
        "type": "service",
        "accountType": "tenant",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "createdAt": "2024-05-08T15:01:39.726373Z",
    "updatedBy": {
        "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
        "type": "service",
        "accountType": "tenant",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "updatedAt": "2024-05-08T15:01:39.732Z",
    "macAddresses": [
        "02:02:03:04:07:50",
        "02:02:04:05:08:35"
    ]
}

Clear MAC filters¶

PUT /switch/v1/settings/mac-filtering

Note: Sending an empty list clears all entries from the blocked MAC address list.

Request body:

{
    "macAddresses": []
}

Response:

{
    "tenant": {
        "id": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "createdBy": {
        "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
        "type": "service",
        "accountType": "tenant",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "createdAt": "2024-05-08T15:01:39.726373Z",
    "updatedBy": {
        "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
        "type": "service",
        "accountType": "tenant",
        "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
    },
    "updatedAt": "2024-05-08T15:01:39.732Z",
    "macAddresses": []
}

Tasks¶

Get tasks¶

A task is a set of policies pushed from Sophos Fusion to the switches. Tasks maintain the status of the applied policy for each switch to which it has been pushed. Tasks are deleted after 30 days.

Call this API to get task details for the tenant.

GET /switch/v1/tasks

Response: This returns the created tasks for the tenant. Here's an example:

{
    "items": [
        {
            "id": "43ccb0b9-c94f-4aa7-88b9-12219949ea8a",
            "type": "macFilters",
            "tenant": {
                "id": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
            },
            "createdBy": {
                "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
                "type": "service",
                "accountType": "tenant",
                "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
            },
            "createdAt": "2024-04-01T07:32:28.672586Z",
            "updatedBy": {
                "id": null,
                "type": null,
                "accountType": null,
                "accountId": null
            },
            "updatedAt": "2024-04-06T13:26:16.925Z",
            "status": {
                "succeeded": 1,
                "failed": 1,
                "pending": 2,
                "noSupportSubscription": 0,
                "total": 3
            },
            "switches": [
                {
                    "id": "eb6fb055-9367-40b6-9564-c575895853f5",
                    "status": "pending",
                    "error": null
                },
                {
                    "id": "a68f526c-27c7-4df3-966a-e6c4193a8dec",
                    "status": "pending",
                    "error": null
                },
                {
                    "id": "ce4e5628-0043-4649-af50-cab3af0e60c2",
                    "status": "succeeded",
                    "error": null
                },
                {
                    "id": "867df519-f483-41f3-9799-30d3b6d926e0",
                    "status": "failed",
                    "error": {
                      "error": "badRequest",
                      "message": "The MAC address filter already exists",
                      "code": "10905",
                      "docUrl": "/guides/switch-management.md"
                    }
                },
            ]
        },
        {
            "id": "df6eb74e-d63c-4b0f-8c51-7ec366686f0c",
            "type": "vlan",
            "tenant": {
                "id": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
            },
            "createdBy": {
                "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
                "type": "service",
                "accountType": "tenant",
                "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
            },
            "createdAt": "2024-04-28T09:02:05.069001Z",
            "updatedBy": {
                "id": null,
                "type": null,
                "accountType": null,
                "accountId": null
            },
            "updatedAt": "2024-04-28T09:02:12.787Z",
            "status": {
                "succeeded": 1,
                "failed": 0,
                "pending": 2,
                "noSupportSubscription": 0,
                "total": 3
            },
            "switches": [
                {
                    "id": "ce4e5628-0043-4649-af50-cab3af0e60c2",
                    "status": "succeeded",
                    "error": null
                },
                {
                    "id": "a68f526c-27c7-4df3-966a-e6c4193a8dec",
                    "status": "pending",
                    "error": null

                },
                {
                    "id": "eb6fb055-9367-40b6-9564-c575895853f5",
                    "status": "pending",
                    "error": null
                }
            ]
        },
    ],
    "pages": {
        "current": 1,
        "size": 100,
        "total": 2,
        "items": 2,
        "maxSize": 1000
    }
}

Call this API with the type and pageSize parameters to get the task details only for the specified criteria.

GET /switch/v1/tasks?type=macFilters&pageSize=1&pageTotal=true

Response: This returns tasks results only for policy type listed in the parameter for the tenant. Here's an example:

{
    "items": [
        {
            "id": "43ccb0b9-c94f-4aa7-88b9-12219949ea8a",
            "type": "macFilters",
            "tenant": {
                "id": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
            },
            "createdBy": {
                "id": "66e5ab4b-1283-4be1-a6a5-ecbf21fb8f79",
                "type": "service",
                "accountType": "tenant",
                "accountId": "1bdb604c-0afe-4bd5-9d4a-2a5d7ffd0da8"
            },
            "createdAt": "2024-04-01T07:32:28.672586Z",
            "updatedBy": {
                "id": null,
                "type": null,
                "accountType": null,
                "accountId": null
            },
            "updatedAt": "2024-04-06T13:26:16.925Z",
            "status": {
                "succeeded": 1,
                "failed": 1,
                "pending": 2,
                "noSupportSubscription": 0,
                "total": 3
            },
            "switches": [
                {
                    "id": "eb6fb055-9367-40b6-9564-c575895853f5",
                    "status": "pending",
                    "error": null
                },
                {
                    "id": "a68f526c-27c7-4df3-966a-e6c4193a8dec",
                    "status": "pending",
                    "error": null
                },
                {
                    "id": "ce4e5628-0043-4649-af50-cab3af0e60c2",
                    "status": "succeeded",
                    "error": null
                },
                {
                    "id": "867df519-f483-41f3-9799-30d3b6d926e0",
                    "status": "failed",
                    "error": {
                      "error": "badRequest",
                      "message": "The MAC address filter already exists",
                      "code": "10905",
                      "docUrl": "/guides/switch-management.md"
                    }
                },
            ]
        }
    ],
    "pages": {
        "current": 1,
        "size": 1,
        "total": 2,
        "items": 2,
        "maxSize": 1000
    }
}

Switch Error List¶

Policy Type	Error Code	Description
Mac Filters	10905	Duplicate MAC filter policy
Mac Filters	10906	MAC filter list is exhausted
Mac Filters	10908	MAC address already allowed in the static MAC table

Conclusion¶

See the API reference for a comprehensive description of the Switch Management API.