New API routes

We have just updated two APIs with new API routes:

Common v1: You can now manage users and groups for a tenant.
Endpoint v1: You can manage global endpoint settings such as allowed/blocked items, and Web Control local sites.

Common v1 changes¶

The first set of routes are under /common/v1/directory. Here's how you can add a new user to a tenant's directory:

POST /common/v1/directory/users

Request body:

{
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com"
}

A successful response looks like this:

{
  "id": "55b19b82-2fcb-40db-b15b-d691e49e25b1",
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "tenant": { "id":  "e0c2c452-1119-421f-96ac-d8f5d0a8b23e" },
  "groups": {
    "total": 0,
    "itemsCount": 0,
    "items": []
  },
  "source": { "type": "custom" }
}

You can find groups using this API:

GET /common/v1/directory/user-groups?fields=name&pageTotal=true

This returns a page of group objects:

{
  "items": [
    { "id": "5f5f1846-499c-4f55-9f3d-9cdcbd7e32ab", "name": "Finance" },
    { "id": "0ca70f33-4e74-4d88-8962-a1ab99b77198", "name": "All staff" },

    ... (48 other group objects)
  ]
  "pages": {
    "current": 1,
    "size": 50,
    "total": 2,
    "items": 93,
    "maxSize": 500
  }
}

Now add the new user to the first two of the groups above:

POST /common/v1/directory/users/55b19b82-2fcb-40db-b15b-d691e49e25b1/groups

With the request body:

{
  "ids": [
    "5f5f1846-499c-4f55-9f3d-9cdcbd7e32ab",
    "0ca70f33-4e74-4d88-8962-a1ab99b77198"
  ]
}

A successful response looks like this:

{
  "addedToGroups": [
    { "id": "5f5f1846-499c-4f55-9f3d-9cdcbd7e32ab", "name": "Finance" },
    { "id": "0ca70f33-4e74-4d88-8962-a1ab99b77198", "name": "All staff" }
  ]
}

You can also specify the groups a user is added to when you create the user. The new API functionality is the same as the options in People in Sophos Central Admin.

Endpoint v1 changes¶

The new routes in the Endpoint v1 API are all under /endpoint/v1/settings and closely match the functionality in Sophos Central Admin:

API route	Page under "Global Settings"
`/endpoint/v1/settings/allowed-items`	"Allowed Applications"
`/endpoint/v1/settings/blocked-items`	"Blocked Items"
`/endpoint/v1/settings/web-control`	"Website Management"
`/endpoint/v1/settings/tamper-protection`	"Tamper Protection"

Here's an example of how you can allow an internal application and prevent it from being blocked.

POST /endpoint/v1/settings/allowed-items

With the request body:

{
  "type": "path",
  "properties": {
    "path": "C:\\bin\\AcmeApp.exe"
  },
  "comment": "Allow AcmeApp.exe everywhere",
}

Fetch a list of website categories:

GET /endpoint/v1/settings/web-control/categories

The response looks like this:

{
  "items": [
    { "id": 0, "label": "Uncategorized" },
    { "id": 1, "label": "Adult/Sexually Explicit" },
    { "id": 2, "label": "Advertisements & Pop-Ups" },
    { "id": 3, "label": "Alcohol & Tobacco" },
    { "id": 4, "label": "Arts" },

    ... (52 other category objects)
  ]
}

Then you can classify an existing website as "Advertisements & Pop-Ups", as follows:

POST /endpoint/v1/settings/web-control/local-sites

Request body:

{
  "url": "offers.example.com",
  "categoryId": 2,
  "comment": "Blocking this website as it has too many popups"
}

Here's how you can check whether Tamper Protection is globally enabled:

GET /endpoint/v1/settings/tamper-protection

The response looks like this:

{
  "enabled": <true|false>
}

All our API updates are backwards compatible. As always, please send us feedback, or get in touch through your Sophos account manager -- we'd love to hear from you!