Getting started

Overview¶

The Wi-Fi Management API allows you to manage access point 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 Wi-Fi 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 Wi-Fi Management API takes the following 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 access point 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, /wifi/v1/settings/mac-filtering.

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

GET /wifi/v1/settings/mac-filtering

To complete the API request, you must expand this to the full form shown above.

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

Terminology¶

Before you use the Wi-Fi Management API, here are a few terms you should know:

Access Point: A hardware appliance that connects devices within a network and allows them to communicate with each other.
Task: Tasks help verify that configured policies are successfully applied to the access point.

Policy management¶

MAC filters¶

Get MAC filters¶

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

GET /wifi/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 /wifi/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 /wifi/v1/settings/mac-filtering

Note: Sending an empty list will clear 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 access points. Tasks maintain the status of the applied policy for each access point to which it has been pushed. Tasks are deleted after 30 days.

Call this API to get task details for the tenant.

GET /wifi/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
            },
            "accessPoints": [
                {
                    "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": null,
                      "docUrl": null
                    }
                },
            ]
        },
        {
            "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
            },
            "accessPoints": [
                {
                    "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 /wifi/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
            },
            "accessPoints": [
                {
                    "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": null,
                      "docUrl": null
                    }
                },
            ]
        }
    ],
    "pages": {
        "current": 1,
        "size": 1,
        "total": 2,
        "items": 2,
        "maxSize": 1000
    }
}

Conclusion¶

See the API reference for a comprehensive description of the Wi-Fi Management API.