Guide — Packages

Overview¶

The Endpoint Software API allows you to view the software packages available for your computers and servers.

This feature currently supports Windows computers and servers.

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:

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" role for API calls to succeed.

Terminology¶

Recommended packages. These are used by any endpoint that has not been specifically configured to use another package. There is a single recommended package for each endpoint type at a time for a given tenant.
Static Packages. These are fixed snapshots of endpoint products that you can assign to endpoints.
Special Packages. These are packages made available by Sophos support if you've issues with our software.

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 either GET, POST or DELETE.
<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/software.

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

GET /endpoint/v1/software/packages/static

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

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

Viewing software packages¶

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

Recommended packages¶

To view all recommended packages:

API: GET /endpoint/v1/software/packages/recommended

Headers:

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

Response:

{
  "items": [
    {
      "id": "recommended-winep",
      "platform": "windows", // windows, linux, macOS
      "endpointType": "computer", // computer, server
      "modules": [
        {
          "name": "coreAgent",
          "version": "2022.1.0.40"
        },
        {
          "name": "deviceEncryption",
          "version": "2022.1.1.67"
        },
        {
          "name": "interceptX",
          "version": "2022.4.1.1"
        }
      ]
    }
  ]
}

Static packages¶

Static Packages have both a releasedAt and expiresAt field to provide more information on whether the package is still supported. Sorting is available for the releasedAt and expiresAt fields. Filtering is available for the releasedAt, expiresAt, type and endpointType fields.

To view all static packages that are available to you:

API: GET /endpoint/v1/software/packages/static

Headers:

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

Response:

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "February 2022",
      "releasedAt": "2022-02-12",
      "expiresAt": "2022-05-12",
      "type": "fixed", // fixed, special, lts
      "platform": "windows",
      "endpointType": "computer", // computer, server
      "packageNotesUrl": "https://docs.sophos.com/releasenotes/output/en-us/esg/sesc_interceptx_rn.html",
      "modules": [
        {
          "name": "coreAgent",
          "version": "2022.1.0.40"
        },
        {
          "name": "deviceEncryption",
          "version": "2022.1.1.67"
        },
        {
          "name": "interceptX",
          "version": "2022.4.1.1"
        }
      ],
      "visible": true
    }
  ]
}

To view the details of a specific static package:

API: GET /endpoint/v1/software/packages/static/<static-package-id>

Headers:

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

Response:

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "February 2022",
      "releasedAt": "2022-02-12",
      "expiresAt": "2022-05-12",
      "type": "fixed", // fixed, special, lts
      "platform": "windows",
      "endpointType": "computer", // computer, server
      "packageNotesUrl": "https://docs.sophos.com/releasenotes/output/en-us/esg/sesc_interceptx_rn.html",
      "modules": [
        {
          "name": "coreAgent",
          "version": "2022.1.0.40"
        },
        {
          "name": "deviceEncryption",
          "version": "2022.1.1.67"
        },
        {
          "name": "interceptX",
          "version": "2022.4.1.1"
        }
      ],
      "visible": true
    }
  ]
}

404 Not Found is returned if no static package with id static-package-id exists.

Special packages¶

Occasionally, you may encounter issues with our software that require a quick patch. To release a patch, Sophos support will make a "special" static package available to you by providing you with a token, which is the ID of the package. Making a special package available is permanent and the package will remain available until it expires.

Provided you have received a valid token, information about the package can be retrieved through the GET request provided above, using the token as the package ID.

API: GET /endpoint/v1/software/packages/static/<special-package-id>

Headers:

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

Response body:

{
  "id": "2af85f64-5717-3176-b3fc-2c963f66baca", // id of the special package
  "name": "Special release Oct/24",
  "releasedAt": "2024-10-05",
  "expiresAt": "2024-11-05",
  "type": "special",
  ...
  "visible": false    // not visible from API, not assignable to policies
}

To add a special package:

API: POST /endpoint/v1/software/packages/static/<special-package-id>/add

Headers:

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

This request takes an empty body. If the token is valid, the response body shows the details of the newly added package:

{
  "id": "2af85f64-5717-3176-b3fc-2c963f66baca", // id of the package just added
  "name": "Special release Oct/24",
  "releasedAt": "2024-10-05",
  "expiresAt": "2024-11-05",
  "type": "special",
  ...
  "visible": true    // this is now set to true as the package has been enabled
}

404 Not Found is returned if no special packages with id special-package-id exists. 409 Conflict is returned if you have already added the package with id special-package-id.

This entry will, from now on, also appear in the list returned when calling GET /endpoint/v1/software/packages/static, as described above.

Comments¶

You can add comments (strings of up to 5000 characters) to a static package, to help you identify which packages are used for which purpose. This includes "special" packages.

To add a comment to a static package:

API: PUT /endpoint/v1/software/comments/<static-package-id>

Headers:

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

Request body:

{
  "comment": "An example of a comment"
}

Response:

{
  "package": { // the static package to which a comment has been added
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "February 2022",
    ...
  },
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // id of the static package
  "comment": "An example of a comment" // your comment
}

To view all the comments you have added to static packages:

API: GET /endpoint/v1/software/comments

Headers:

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

Response body:

{
  "items": [
    {
      "package": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        ...
      },
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "comment": "Example comment 1"
    },
    {
      "package": {
        "id": "f3a85f64-5717-4562-b3fc-2c963f66afa6",
        ...
      },
      "id": "f3a85f64-5717-4562-b3fc-2c963f66afa6",
      "comment": "Example comment 2"
    }
  ]
}

If a static package has no comment, then that package and its comment will not be included in the response (only static packages with comments are returned from this request).

To view the comment you have added to a specific static package:

API: GET /endpoint/v1/software/comments/<static-package-id>

Headers:

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

Response body:

{
  "package": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    ...
  },
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // id of the static package
  "comment": "Use this package for tills"
}

404 Not Found is returned if no static package with id static-package-id exists, or if no comment exists for that static package.

To delete a comment you have already added to a static package:

API: DELETE /endpoint/v1/software/comments/<static-package-id>

Headers:

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

Response body:

{
  "success": true // true or false
}

404 Not Found is returned if no static package with id static-package-id exists, or if no comment exists for that static package.

Conclusion¶

After reading this guide, you should be able to use the new API routes in the Endpoint API to view the packages available to you for your endpoint software.