Guide — Device Software

Overview¶

You can manage device software assignments for endpoints using the Device Software API. Use it to set protection, encryption, and ZTNA device software for computers, and protection device software for servers, in bulk.

This API manages a single tenant at a time.

Requirements¶

You must have a set of API credentials (service principal) to call the Device Software 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 Enterprise to manage multiple tenants, read the Organization Getting Started guide first.

Other customers: Read the Tenant Getting Started guide first.

Note: Your API credentials must have the Service Principal Super Admin or Service Principal Management role for API calls to succeed, and permission to update the endpoints you target (endpoint-computer:update when changing computer assignments, and/or endpoint-server:update when changing server assignments).

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

Making API requests¶

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 Device Software 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/device-software.

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

PATCH /endpoint/v1/device-software

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

All successful and partially successful API requests return HTTP status code 200.

Terminology¶

Device software values on each endpoint are chosen from the Aurora catalog. In the request body, each assignment field (protectionAssignedId, encryptionAssignedId, ztnaAssignedId) accepts one of the following:

All: Assign the highest device software the account is licensed for, for that category only, to every endpoint ID listed under the corresponding computer or server block. For example, setting protectionAssignedId to All only assigns the highest protection device software—it does not assign encryption or ZTNA.
None: Remove all device software of that category that is currently assigned to those endpoints. For example, setting encryptionAssignedId to None only removes encryption—it does not affect protection or ZTNA.
<deviceSoftwareId>: A specific ID string from the catalog; the API attempts to apply that device software to the listed endpoints.

Note: IDs are case-sensitive.

To get a list of available device software IDs, see How to discover available device software IDs.

Computer blocks may include protectionAssignedId, encryptionAssignedId, and ztnaAssignedId. Each computer section must contain ids and at least one of protectionAssignedId, encryptionAssignedId, or ztnaAssignedId when you are updating assignments.

Server blocks may only include protectionAssignedId (in addition to ids). Each server section must contain ids and protectionAssignedId when you are updating server assignments.

You may send a computer section only, a server section only, or both.

Categories of device software¶

When assigning device software, you control up to three categories on computers (and protection on servers).

Protection¶

Protection device software includes the core endpoint security stack. Use the protectionAssignedId field to assign it.

Encryption¶

Encryption device software provides device encryption capabilities. Use the encryptionAssignedId field. Computers only.

ZTNA¶

ZTNA (Zero Trust Network Access) device software enables secure network connectivity. Use the ztnaAssignedId field. Computers only.

Update assigned device software¶

Call this API to update device software for up to 1000 endpoint IDs per computer or server section in a single request:

PATCH /endpoint/v1/device-software

Headers:

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

The request body lists endpoint UUIDs and the device software to assign for each category you specify:

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

Request shape:

computer (optional): Contains ids (required, 1–1000 UUIDs) and at least one of protectionAssignedId, encryptionAssignedId, or ztnaAssignedId when updating.
server (optional): Contains ids (required, 1–1000 UUIDs) and protectionAssignedId when updating server device software.

You may send computer only, server only, or both, depending on which endpoints you are updating.

The API processes each endpoint individually. A successful response lists which endpoint IDs were updated and any per-endpoint failures:

{
  "updated": [
    "a48f76c0-fc26-4e6f-b66d-fbbe8db6e90e"
  ],
  "errors": [
    {
      "id": "5b2f8622-a17b-40a0-a428-bc22fce49790",
      "code": "notFound"
    }
  ]
}

updated: Endpoint IDs whose assigned device software was changed successfully.
errors (optional): Entries for endpoints that could not be updated; each item includes the endpoint id and a string code.

See Error handling for HTTP status codes and partial success behavior.

How to discover available device software IDs¶

To see which deviceSoftwareIds you can apply for a given endpoint, call GET /endpoint/v1/endpoints/{endpointId} and inspect the response. The available node shows the device software that can be applied to that endpoint (within your license and catalog).

Use those IDs when you set assignment fields to a specific <deviceSoftwareId> instead of All or None.

Error handling¶

When updating device software in bulk, the API processes each endpoint individually. If some endpoints fail to update, the API still returns HTTP 200 and lists successes in updated and failures in errors.

Other common responses:

403: Authorization required. This response can occur if you use and invalid token or don't use API credentials with the Service Principal Super Admin or Service Principal Management roles).
500: Internal server error.

Error codes in errors[].code are returned as strings. For example:

{
  "updated": [
    "a48f76c0-fc26-4e6f-b66d-fbbe8db6e90e"
  ],
  "errors": [
    {
      "id": "5b2f8622-a17b-40a0-a428-bc22fce49790",
      "code": "notFound"
    },
    {
      "id": "04a2cba3-92e3-43f1-88b2-3e0baa3c877c",
      "code": "No device found of type:computer"
    }
  ]
}

In this example, one endpoint was updated while two others failed with different error codes.

Limitations¶

Bulk size: Up to 1000 endpoint UUIDs per ids array under each of computer and server.
Proxy: Integrations must use the endpoint-state-query proxy as required by your environment.

Conclusion¶

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

Assign device protection, encryption, and ZTNA software for computers, and device protection software for servers
Interpret updated and errors in the response, including partial success.
Discover valid IDs using GET /endpoint/v1/endpoints/{endpointId}.