Skip to content

Assigned Software Packages

Overview

The Assigned Software Packages API allows you to install additional Sophos software on computers or servers that are already protected or managed by Sophos Fusion. You can also uninstall existing software.

Pre-requisites

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

Note: Your API credentials must have the "Service Principal Super Admin" or "Service Principal Management" role for API calls to succeed.

Making API requests

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

When using curl, a request to the Endpoint 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 Endpoint API, this is PATCH.
  • <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 geography where the tenant data is located.
  • <path>: The request path for the API operation, for example endpoint/v1/settings/assigned-software/packages.

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

PATCH /endpoint/v1/settings/assigned-software/packages

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

All API requests return HTTP status code 200 when successful.

Assigning software packages to endpoints

The following API call may be invoked by a service principal.

Update assigned packages in bulk

You can assign specific protection, encryption, and ZTNA packages to multiple endpoints in a single request.

API: PATCH /endpoint/v1/settings/assigned-software/packages

Headers:

  • Authorization: Bearer <jwt>
  • X-Tenant-ID: <uuid>

Request body:

{
  "computer":
  {
    "ids": [
      "6ddbdc1f-d67b-4a41-baf3-66745ffd79d1", "b45cd39d-8b6c-49f1-905f-06b021496d91"
    ],
    "protectionAssignedId": "XDR",
    "encryptionAssignedId": "All",
    "ztnaAssignedId": "None"
  },
  "server":
  {
    "ids": [
      "b381536f-ce4e-41d6-9ea1-400702fe95b6"
    ],
    "protectionAssignedId": "All"
  }
}

Request parameters:

  • computer (optional): Package assignments for computers. Must contain:
    • ids (required): Array of computer endpoint IDs to update (1-1000 items)
    • At least one of the following:
      • protectionAssignedId (optional): The package ID for protection software
      • encryptionAssignedId (optional): The package ID for encryption software
      • ztnaAssignedId (optional): The package ID for ZTNA software
  • server (optional): Package assignments for servers. Must contain:
    • ids (required): Array of server endpoint IDs to update (1-1000 items)
    • protectionAssignedId (required): The package ID for protection software

Note: You can use the following package ID values:

  • All: Assigns the highest package the user is licensed for to the endpoints in the ids list
  • None: Removes all packages assigned to the endpoints in the ids list
  • packageId: Attempts to apply the specific package ID to the endpoints in the ids list

To get a list of available package IDs, query the /endpoint/v1/endpoints/{endpointId} API. The available node will show which packages can be applied to the endpoint.

Response:

{
  "updated": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "errors": [
    {
      "id": "6fa85f64-5717-4562-b3fc-2c963f66afa9",
      "code": "ENDPOINT_NOT_FOUND"
    }
  ]
}

The response includes:

  • updated: Array of endpoint IDs that were successfully updated
  • errors (optional): Array of errors for endpoints that failed to update, each containing:
    • id: The endpoint ID that failed
    • code: An error code describing the failure

Understanding package types

When assigning software packages to endpoints, you can control three different types of packages:

Protection packages

Protection packages contain the core endpoint security software.

Use the protectionAssignedId field to assign protection packages to endpoints.

Encryption packages

Encryption packages provide device encryption capabilities to secure data on endpoints.

Use the encryptionAssignedId field to assign encryption packages to endpoints.

ZTNA packages

ZTNA (Zero Trust Network Access) packages enable secure network connectivity.

Use the ztnaAssignedId field to assign ZTNA packages to endpoints.

Error handling

When updating assigned packages in bulk, the API processes each endpoint individually. If some endpoints fail to update, the API will still return success for those that were updated successfully.

Example response with partial success:

{
  "updated": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "4fa85f64-5717-4562-b3fc-2c963f66afa7"
  ],
  "errors": [
    {
      "id": "5fa85f64-5717-4562-b3fc-2c963f66afa8",
      "code": "INVALID_PACKAGE_ID"
    },
    {
      "id": "6fa85f64-5717-4562-b3fc-2c963f66afa9",
      "code": "ENDPOINT_NOT_FOUND"
    }
  ]
}

In this example, 2 endpoints were successfully updated while 2 failed with different error codes.

Conclusion

After reading this guide, you should be able to use the API routes in the Endpoint API to:

  • Assign specific software packages to individual endpoints
  • Update protection, encryption, and ZTNA packages in bulk
  • Handle errors and partial failures gracefully

For more information on viewing available software packages, see the Endpoint Software API guide.