Working with groups

The groups endpoints return your employee groups as the Groups page in Secfix shows them: member counts, the onboarding tasks assigned to each group, and each group’s settings. Groups are read-only in the API. Reads require Read access (all:read). See Scopes.

List groups

GET /v1/groups returns a cursor-paginated list of groups, oldest first.

curl "https://api.secfix.com/v1/groups?pageSize=50" \
  -H "Authorization: Bearer $TOKEN"

To filter by name, pass name with up to 50 group names, comma-separated. Names are matched case-insensitively:

curl "https://api.secfix.com/v1/groups?name=Engineering,Sales" \
  -H "Authorization: Bearer $TOKEN"

To list a group’s employees, pass its id as groupId to GET /v1/employees.

Fields

Field	Meaning
`id`	Group id.
`name`	Group name.
`isDefault`	`true` for your workspace’s default group, which new employees join.
`memberType`	Who the group holds: `PEOPLE` or `SERVICE_ACCOUNTS`. Left out when not set. A group without a `memberType` counts no members.
`employeeCount`	Active members of the group who are included in compliance. This is the count the Groups page shows.
`createdAt`	When the group was created. Left out for older groups created before Secfix recorded this.
`tasks`	The onboarding tasks assigned to the group. See Tasks.

Tasks

tasks lists the onboarding tasks the Groups page shows on the group: trainings first, then device monitoring, then policies. Each task has a key, name, and category (TRAINING, MONITORING, or POLICIES). A task is listed when it is assigned to the group and enabled for your workspace’s frameworks. Policy acceptance is listed only when at least one policy is assigned to the group. Task keys are stable, but new keys may be added. Treat an unknown key as opaque.

Get a group

GET /v1/groups/{id} returns one group with its settings, as the group’s settings in the Secfix app show them. An unknown id returns 404 not_found.

curl "https://api.secfix.com/v1/groups/$GROUP_ID" \
  -H "Authorization: Bearer $TOKEN"

It returns the list fields plus:

Field	Meaning
`trainings`	Every training enabled for your workspace’s frameworks, in the order the Secfix app shows them. Each has `key`, `name`, `description` (when set), and `enabled` (whether it’s assigned to this group).
`deviceMonitoring`	`enabled` (whether device monitoring is assigned to this group) and `subTasks`: its steps in the order the Secfix app shows them, such as installing the Secfix agent or configuring MDM. Each step has `key`, `name`, and `enabled`.
`policyAcceptance`	`enabled` (whether policy acceptance is assigned to this group) and `policies`: the approved policies the group’s members must accept, each with `id` and `name`. Secfix policies come first, then custom policies, each sorted by name.

{
  "id": "9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e",
  "name": "Engineering",
  "isDefault": false,
  "memberType": "PEOPLE",
  "employeeCount": 12,
  "tasks": [
    { "key": "SECURITY_AWARENESS_TRAINING", "name": "Security awareness training", "category": "TRAINING" }
  ],
  "trainings": [
    { "key": "SECURITY_AWARENESS_TRAINING", "name": "Security awareness training", "enabled": true }
  ],
  "deviceMonitoring": {
    "enabled": true,
    "subTasks": [
      { "key": "SECFIX_AGENT", "name": "Install the Secfix agent", "enabled": true }
    ]
  },
  "policyAcceptance": {
    "enabled": true,
    "policies": [
      { "id": "5e8f0a1b-2c3d-4e5f-9a6b-7c8d9e0f1a2b", "name": "Acceptable Use Policy" }
    ]
  }
}

When device monitoring isn’t assigned to the group, its steps show enabled: false. The MDM step is the exception: it keeps its own value.

Get started

Core concepts

Guides

List groups

Fields

Tasks

Get a group

​List groups

​Fields

​Tasks

​Get a group

List groups

Fields

Tasks

Get a group