Skip to content

Getting started

Overview

This API allows you to create and manage access tokens for Sophos hosted package repositories. You can configure a package manager with an access token, allowing it to authenticate with a package repository and install or update the Sophos Linux Sensor packages.

Note: These access tokens can't be used to call the Sophos Fusion APIs.

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:

Creating an access token will fail unless the tenant has a valid license for one of the following products:

  • Intercept X Advanced for Server with XDR
  • Intercept X Advanced for Server with XDR and MTR Standard
  • Intercept X Advanced for Server with XDR and MTR Advanced

The following APIs must be invoked using admin API credentials.

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 or POST.
  • <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 accounts/v1/access-tokens.

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

POST /accounts/v1/access-tokens

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.

Manage access tokens

Create an access token

API: POST /accounts/v1/access-tokens

Headers:

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

Request Body:

{
  "label": "Test Token",            // Required.
  "type": "sophosLinuxSensor",          // Required. Currently, only this value is supported.
  "expiresAt": 2023-04-29T15:32:28.482Z     // Optional. Desired expiry date.
}

Response:

{
  "id": "98a2ebb7-4628-4340-b80b-cef6c9dbf8e6",   // Unique ID for the access token.
  "token": "SLS-UL65R1TVEE1MZDHZ",                // Access token to be used by clients.
  "type": "sophosLinuxSensor",            // Access token type.
  "label": "Test Label",                  // Custom label that was provided.
  "createdAt": "2022-06-29T15:22:13.307Z",    // When the access token was created.
  "expiresAt": "2023-04-29T15:32:28.482Z",    // When the access token expires.
  "url": "https://packages.sophos.com",       // Package repository URL.
  "createdBy": {...}                  // Who created the access token.
}

Errors:

403 - The tenant does not have one of the required licenses for Sophos Linux Sensor

Limitation:

  • Each tenant can create a maximum of 50 access tokens.
  • The expiry date specified in the request must not exceed the expiry date of the tenant's associated server license. If it does the requested expiry date is adjusted to match the expiry date of the associated license.
  • The description specified in the request can have up to 50 characters. These can be any combination of alphanumeric characters, spaces, commas, hyphens and periods.

Revoke an access token

Use this API to revoke an existing access token.

API: DELETE /accounts/v1/access-tokens/{tokenId}

For example: DELETE /accounts/v1/access-tokens/98a2ebb7-4628-4340-b80b-cef6c9dbf8e6

Headers:

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

Response:

{
  "deleted": true
}

Update an access token

Call this API to update the label for an access token, its expiry date, or both.

API: PATCH /accounts/v1/access-tokens/{tokenId}

For example: PATCH /accounts/v1/access-tokens/98a2ebb7-4628-4340-b80b-cef6c9dbf8e6

Headers:

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

Request:

{
  "label": "Label123",                  // Optional. The new label.
  "expiresAt": 2023-04-29T15:32:28.482Z     // Optional. The new expiry date.
}

Response: Returns the updated access token.

{
  "id": "98a2ebb7-4628-4340-b80b-cef6c9dbf8e6",
  "token": "SLS-UL65R1TVEE1MZDHZ",
  "type": "sophosLinuxSensor",
  "label": "Label123",
  "createdAt": "2022-06-29T15:22:13.307Z",
  "expiresAt": "2028-04-29T15:32:28.482Z",
  "url": "https://packages.sophos.com",
  "createdBy": {...}
}

List all existing access tokens

Call this API to enumerate access tokens.

API: GET /accounts/v1/access-tokens

Headers:

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

Supported query parameters:

  • page - which page of access tokens to fetch
  • pageSize - how many access tokens to fetch on each page
  • pageTotal - whether to show the total number of access tokens available across all pages

Response: Returns a page of access tokens.

{
  "items": [
    {
      "id": "98a2ebb7-4628-4340-b80b-cef6c9dbf8e6",
      "token": "SLS-UL65R1TVEE1MZDHZ",
      "type": "sophosLinuxSensor",
      "label": "Test Token",
      "createdAt": "2022-06-29T15:22:13.307Z",
      "expiresAt": "2023-04-29T15:32:28.482Z",
      "url": "https://packages.sophos.com",
      "createdBy": {...}
    },
    {
      "id": "f55aa6bb-22b1-44e1-8ba5-6958d08df5ba",
      "token": "SLS-KVCDWURDJKNCZBOI",
      "type": "sophosLinuxSensor",
      "label": "Test Token 2",
      "createdAt": "2022-06-13T09:21:38.822Z",
      "expiresAt": "2023-04-29T15:32:28.482Z",
      "url": "https://packages.sophos.com",
      "createdBy": {...}
    }
  ],
  "pages": {
    "current": 1,   // Current page.
    "size": 50,     // Page size.
    "items": 2,     // Total number of items across all pages.
    "maxSize": 50   // Maximum page size that can be requested.
  }
}

Currently there is a maximum limit of 50 access tokens per tenant, so pagination isn't necessary for the default page size of 50.

To fetch the next page of results pass in page=2 as a query param.

For example, GET /accounts/v1/access-tokens?page=2&pageSize=50pageTotal=true.

Conclusion

You should now be able to use the access token management operations in the new Accounts API. See the reference guide for more details.