/portalAPI/ComputerGroup/*

This article will encompass all portalAPI calls that are related to /portalAPI/ComputerGroup/* endpoints

 

If you are new to working with ThreatLocker PortalAPI endpoints and/or have questions regarding authentication and terminology used throughout this article, please look through the following guide:

Getting Started with ThreatLocker PortalAPIs

ComputerGroupGetById

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupGetById

• Method: GET
• Description: This API is primarily used when navigating to the Assets icon and selecting the Groups page from the pop-out menu in the ThreatLocker Portal, then locating and selecting the group whose information you want to view. This API is also used whenever the computer group sidebar is accessed in the Portal. This API returns detailed group information for the selected group. Ensure that the managedOrganizationId header you use matches the location where the group exists.
• Required Body/Parameters
  • Parameters
    • computerGroupId: This field determines which group's information will be returned. To get a list of computerGroupIds, use the ComputerGroupGetByParameters API.
      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
• Optional Body/Parameters
  
  • N/A
• Permission Requirements
  • Assign any one of the following permissions:

  • • Edit Computer Groups
    • Install Computers
    • View Computer Groups

ComputerGroupGetByParameters

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupGetByParameters

• Method: POST
• Description: This API is used when navigating to the Assets icon and selecting the Groups page from the popout menu in the ThreatLocker Portal. This API is also used when selecting the Groups tab when in another portion of the Assets section of the Portal. This API returns all your device groups based on the fields you select. Ensure that the managedOrganizationId you use matches the location where you want to view your groups.
• Required Body/Parameters
  • Fields

  • • osType: This field determines the OS Type of the groups that will be returned. This field expects the Integer associated with the OS Type:

  • • • All = 0
      • Windows = 1
      • MAC = 2
      • Linux = 3
      • Windows XP = 5
      • Android = 11
      • iOS = 10
      • Ingester = 6
      • External = 12
    • pageNumber and pageSize: These fields determine how many groups will be returned, as if the response were on the Device Groups page. However, these fields do not follow the same conventions for pageNumber and pageSize as the Portal does (the Portal uses 25, 50, 100, or 500 for pageSize). Any valid integer can be entered, and the results will be returned in the selected format. For instance, if there are 5 groups to be returned but "pageNumber": 1 and "pageSize": 2, 2 entries will be returned per page, and the first two groups will be shown.

      • Expects: An Integer value

• Optional Body/Parameters
  • Fields
    • searchText: This field allows you to search/narrow the groups returned by inputting any text/details you want to search for. When this field is omitted, all groups will be displayed based on the other search fields. When text is entered into this field and showAllGroups is set to true, it searches for results by organization name and group name. When text is entered into this field and showAllGroups is omitted or set to false, it searches for results by group name only. This field searches case-insensitively and effectively uses wildcards on either side of the entered text. For example, entering "Work" into this field will return any group whose name contains "Work," as well as any groups belonging to an organization whose name contains "Work."

      • Expects: Any text input
    • showAllGroups: This field determines whether groups from your child organizations will be returned. When this field is omitted or set to false, only groups from the currently entered managedOrganizationId will be returned. When this field is set to true, all child organization groups, including grandchild organization groups, will be returned.

      • Expects: true or false

• Permission Requirements
  • Assign any one of the following permissions:
    • Edit Computer Groups
    • Install Computers
    • View Computer Groups

ComputerGroupGetDropdownWithOrganization

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupGetDropdownWithOrganization

• Method: GET
• Description: This API is used when copying policies from their respective pages, when looking to move computers on the Devices page, and when selecting to view computers from all child organizations on the Devices page in the ThreatLocker Portal. This API will return a list of all computer groups, including child organizations, and the organizations where they apply. This can be used to get all of the computer groups that can be installed into. The “label” field indicates the name of the organization or computer group. The “value” field is the organzationId or computerGroupId. When using the managedOrganizationId header, only the current organization and any child of the current organization will be displayed, unless the includeAvailableOrganizations field is used as described below.
• Required Body/Parameters
  • N/A
• Optional Body/Parameters
  • includeAvailableOrganizations: Will include a list of all the computer groups, including child AND parent organizations, and the organizations where they apply for any organization the effectively "logged in"/authenticated user has access to, regardless of the managedOrganizationId passed in.
• Permissions Needed for User
  • Edit Computers
  • Edit Computer Groups
  • View Computers

ComputerGroupGetDropdownByOrganizationId

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupGetDropdownByOrganizationId

• Method: GET
• Description: This API is used on the Devices page in the ThreatLocker Portal when viewing an invidual computer and is typically used to load the computer groups where the computer can be moved to within the organization. This API will return a list of computer groups from a specific organization. To narrow the search results down more to specific OS Types, it is important to use both the computerGroupOSTypeId field and the computerOSType fields. Ensure that the computerGroupOSTypeId and the computerOSType apply to the same operating system and do not conflict. (1 goes with "windows", 2 goes with "mac", etc.). If looking to view the computer groups from a different organization than the currently logged in/managed organization, utilize the managedOrganizationId header.
• Required Body/Parameters
  • N/A
• Optional Body/Parameters
  • computerGroupOSTypeId: This field expexts one of the Intergers from below to be entered AND should correspond with the computerOSType field from below:
    • Windows = 1
    • MAC = 2
    • Linux = 3
    • Windows XP = 5
  • computerOSType: This field expects one of the strings from below to be entered AND should correspond with the ID entered above:
    • "windows"
    • "mac"
    • "linux"
    • "windows xp"
• Permissions Needed for User
  • Edit Computers
  • View Computers
  • Install Computers

ComputerGroupGetForDownload

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupGetForDownload

• Method: GET
• Description: This API is used on the Devices page in the ThreatLocker Portal when selecting the Install Computer button and selecting a computer group to install into. This API will display the installation information for a computer group, including organizationId, name, OSType, whether the EULA has been accepted, whether a computer can be installed into the computer group, and whether there is a valid install link for the group. Utilize the install key for the computer group you would like to return the information from.
• Required Body/Parameters
  • installKey - 24 characters found on the Computer Groups page
• Optional Body/Parameters
  
  • N/A
• Permissions Needed for User
  • Since a valid install key is required to call this, no permissions are required

ComputerGroupGetForPermitApplication

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupGetForPermitApplication

• Method: GET
• Description: This API is used on the Response Center page in the ThreatLocker Portal when responding to an Application Control Approval Request and choosing a specific computer group to apply the request's Application Control policy to. This API populates the dropdown option when selecting Computer Group under the Applies To section of the Approval Request in the ThreatLocker Portal. To view the computer groups available from an Approval Request from a different organization than the currently logged in/managed organization, utlilize the managedOrganizationId header.
• Required Body/Parameters
  • N/A
• Optional Body/Parameters
  
  • osType: This field determines the OS Type of the computer groups you are looking to view. OS Types to select from are listed below. This field expects the Integer associated with the OS Type to be entered:
    • Windows = 1
    • MAC = 2
    • Linux = 3
    • Windows XP = 5
• Permissions Needed for User

  • Approve for Entire Organization

  • Approve for Group

  • Approve for Single Computer

  • Approve for Single Computer Application Only

  • View Approvals

ComputerGroupGetGroupAndComputer

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupGetGroupAndComputer

• Method: GET
• Description: This API is used in most sidebars where policies are configured in the ThreatLocker Portal, including but not limited to, Application Control Policies, Storage Control Policies, and Network Control Policies. This API will retrieve a list of computers and groups depending on the parameters passed into the endpoint. If looking to view the computer groups from a different organization than the currently logged-in/managed organization, utilize the managedOrganizationId header.
• Required Body/Parameters
  • N/A
• Optional Body/Parameters
  • OSType: This field will limit the computer groups displayed to those of the selected OS Type, OS Types to select from are listed below and this field expects the Integer associated with the OS Type:
    • All = 0
    • Windows = 1
    • MAC = 2
    • Linux = 3
    • Windows XP = 5
  • includeGlobal: This field will determine whether the Global group, used for permitting applications on a global scale across your organization(s), is displayed in the results.
    • Expects: true or false
  • includeOrganizations: This field can also include the organizations that the user/currently authorized user has access to. If managing a grandchild organization, only the grand-child organization will be displayed. If managing a child organization, the parent organization and any child organizations of that child will be displayed, a grand-child of the parent organization. 
    • Expects: true or false
  • includeParentGroups: This field will show all the parent computer groups, of the organization currently managed as long as the currently logged-in/authenticated user has access to the organization, including grandparents of the currently managed organization.
    • Expects: true or false
  • includeLoggedInObjects: This field will display additional information in the “label” fields of each computer group, computer, and organizations. For instance, if the organizations that are a direct parent of the currently managedOrganization will show “PARENT\\organizationName”, for the computer groups it will show “organizationName\\computerGroupName”, and for computers it will show “organizationName\\computerGroupName\\computerName”
    • Expects: true or false
• Permissions Needed for User
  • Super Admin

ComputerGroupInsert

Note: While these are the only fields required to call this API, only using these fields will create a new group with the following options:

• No initial Learning for newly installed devices
• No automatic policy creation during any initial Learning period
• Heartbeat interval of 60 seconds
• No excluded processes
• Baseline All Paths
• Each device is created and displayed as a separate device record
• No customer guidelines set at the organization level will be displayed for Cyber Hero Management

• • • name: This field specifies the name of the new group. Any name can be entered, and the computerGroupId and install key will be automatically generated.

      • Expects: Any text input
    • osType: This field determines the OS Type that will be applied to the group that will be created. OS Types to select from are listed below. This field expects the Integer associated with the OS Type. For more information on using the External OS Type, see the KB article below:

• Optional Body/Parameters
  • Fields
    • autoCreatePolicies: This field determines how policies are created during the initial Learning period for the group that will be created. When this field is omitted, the "Do Not Learn" option is selected from the options below. This field expects one of the Integers associated with the option you want. For more information on how these function, see the KB article below:

Changing How Computers Initially Learn Once Deployed (Computer, Group, or System Policies) | ThreatLocker Help Center 

• • • • Do Not Learn = 0
      • Computer Level Policies = 1
      • Device Group Level Policies = 2
      • System Policies for Computer = 3
    • baselineAllPaths: This field determines whether all file paths will be scanned when a Baseline scan is completed on a device in the group that will be created. When this field is omitted or set to true, the group will Baseline all paths. When this field is set to false, all paths except those listed in the baselineOptions field will be scanned. When this field is set to false and the baselineOptions field is unused or contains no entries, it will revert to true when the group is created, and all file paths will be scanned.

      • Expects: true or false
    • baselineOptions: This field determines which file paths will be ignored during a Baseline scan on devices in the group that will be created. This field should only be used when the baselineAllPaths field is set to false. The paths entered into this field will be ignored during the Baseline process, but may be learned during Learning Mode if they execute. Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field in the same way, as in the ThreatLocker Portal, as shown in this example: c:\\users\\*\\Documents\\*

      • Expects: Full file path or partial path with wildcards
    • cyberHeroUseOrgSettings: This field determines whether the group that will be created will use the Cyber Hero Management (CHM) request instructions from the organization. When this field is omitted or set to false, the organization settings will not be used, and instructions for the group can be specified using the tlInstructions field. When this field is set to true, the organization's CHM instructions will be used.

      • Expects: true or false
    • exclusions: This field determines whether any processes will be excluded from processing in the group that will be created. This should only be used in very specific circumstances. Nothing will be blocked or logged in the Unified Audit if the action is performed by the process set to be excluded. No ThreatLocker policies will take effect on processes set to be excluded. When this field is omitted, no processes will be excluded. One or multiple exclusions can be added. As demonstrated in the Optional body section, each exclusion requires all of the fields listed below, except when exclusionType is set to 4. In this case, no file path can be specified; only the fields exclusionType and value should be used. For additional information on excluding processes, see the KB article below:

Excluded Processes | ThreatLocker Help Center

• • • • exclusionType: This field determines the exclusion type that will be applied. This field expects the Integer associated with the exclusion type:

        • Execute = 1
        • Install = 2
        • Storage = 3
        • Network = 4
      • filePath: This field determines if a file path should also be matched with the entered excluded process. If you do not want to specify a file path for this process, you can leave this field as "". Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field, as in the ThreatLocker Portal, as shown in this example: c:\\users\\*\\Documents\\*

        • Expects: Full file path or partial path with wildcards
      • value: This field determines the process that will be excluded. This field expects only a full process name, regardless of the directory (e.g., python.exe, code.exe). Wildcards cannot be used in this field.

        • Expects: Full process name as described above
    • initialMonitorModeHours: This field determines the initial Learning Mode period for the group. When this field is omitted, the initial Learning Mode period will be set to 0. This field expects the length of time to be entered in hours. For display purposes in the Portal, the hours entered into this field are converted to days and hours. The maximum number of hours that can be entered is 90,000 (3,750 days). When entering an Integer between 89,976 and 90,000, the group will be assigned an "Indefinite" Learning period. Anything less than 89,976 will set the Learning period accordingly. When the autoCreatePolicies field is not used, no policies will be created for this Learning period.
      • Expects: Any non-negative Integer value up to and including 90,000

Note: The options applied to the group that will be created in the options field below should be used with extreme care as using these options may greatly impact ThreatLocker's ability to monitor and secure your environment.

Options Tab: Choices and Descriptions | ThreatLocker Help Center

• • • options: This field determines the options that will apply to the group that will be created. When this field is omitted, no options will be applied. One or multiple options can be entered into this field. For each option, enter the text of the option exactly as it appears in the KB article above. The Optional body section below demonstrates how to add four options.

      • Expects: Text of any organization option exactly as listed in the article above
    • permitReplace: This field determines whether devices with the same hostname can reuse the same device record, inherit the same settings, and appear as one device on the Devices page for the group that will be created. When this field is omitted or set to false, this will not be allowed. When this field is set to true, this will be allowed. For additional information, see the KB article below:

Deploying ThreatLocker in a VDI environment | ThreatLocker Help Center

• • • • Expects: true or false
    • policyRefreshIntervalSeconds: This field determines the Heartbeat Interval, how often the ThreatLocker Agent checks in to the Portal, in seconds, which will be assigned to the group that will be created. When this field is omitted, the Heartbeat Interval will be set to 60. The minimum number of seconds that can be entered is 8, and the maximum is 300 (5 minutes).

      • Expects: Any non-negative Integer value from 8 up to and including 300
    • tlInstructions: This field determines the Cyber Hero Management instructions that will be applied to the group that will be created. When this field is omitted, no instructions will be applied. This field should only be used when the cyberHeroUseOrgSettings field is omitted or set to false.

      • Expects: Any text input

• Permission Requirements

  • Assign this permission:

  • • Edit Computer Groups

ComputerGroupUpdateById

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupUpdateById

• Method: POST
• Description: This API is used when navigating to the Assets icon and selecting the Groups page from the pop-out menu in the ThreatLocker Portal, locating and selecting the group you wish to change, making your changes, and selecting "Save". This API updates device groups in your organization. Ensure that the managedOrganizationId header you use matches the location where the group exists.

Be sure to review the Optional Body/Parameters section and check the current configuration of the group you are making changes to. Many fields listed are not required to make the call to this API. However, if some fields are not included, you may unintentionally make changes to your group.

• Required Body/Parameters
  • Fields
    • computerGroupId: This field determines which group will be updated. The computerGroupId must match the group's existing value; it cannot be changed after creation.

      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • name: This field determines the name that will be applied to the group. Any name can be entered. If you do not wish to change the group's name, enter the existing name.

      • Expects: Any text input
    • osType: This field determines the OS Type that will be applied to the group. The OS Type must match the group's existing value; it cannot be changed after creation. This field expects the Integer associated with the OS Type:

      • Windows = 1
      • Mac = 2
      • Linux = 3
      • Windows XP = 5
      • Ingester = 6
      • iOS = 10
      • Android = 11
      • External = 12

• Optional Body/Parameters
  • Fields
    • autoCreatePolicies: This field determines how policies are created during the initial Learning period in the group. When this field is omitted, the "Do Not Learn" option is selected from the options below. This field expects one of the Integers associated with the option you want. If you do not wish to change the initial Learning period's policy creation setting for the group, enter the existing Integer value. For more information on how these settings function, see the KB article below:

Changing How Computers Initially Learn Once Deployed (Computer, Group, or System Policies) | ThreatLocker Help Center

• • • • Do Not Learn = 0
      • Computer Level Policies = 1
      • Device Group Level Policies = 2
      • System Policies for Computer = 3
    • baselineAllPaths: This field determines whether all file paths will be scanned when a Baseline scan is completed on a device in the group. When this field is omitted or set to true, the group will Baseline all paths. When this field is set to false, all paths except those listed in the baselineOptions field will be scanned. When this field is set to false and the baselineOptions field is unused or contains no entries, it reverts to true, and all file paths will be scanned. If this field is omitted and was previously set to false with baselineOptions containing an exclusion, it will default to true, and the group will scan all file paths.

      • Expects: true or false
    • baselineOptions: This field determines which file paths will be ignored during a Baseline scan on devices in the group. This field should only be used when the baselineAllPaths field is set to false. The paths entered into this field will be ignored during the Baseline process, but may be learned during Learning Mode if they execute. Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field, as in the ThreatLocker Portal, as shown in this example: c:\\users\\*\\Documents\\*. If an excluded path is already applied to the group, it will need to be re-entered to keep it applied.

      • Expects: Full file path or partial path with wildcards
    • cyberHeroUseOrgSettings: This field determines whether the group will use the Cyber Hero Management (CHM) request instructions from the organization. When this field is omitted or set to false, the organization settings will not be used, and instructions for the group can be specified using the tlInstructions field. When this field is set to true, the organization's CHM instructions will be used. If this field is omitted and was previously set to true, it will default to false, and the group will not use the organization's instructions.

      • Expects: true or false
    • exclusions: This field determines whether any processes will be excluded from processing in the group. This should only be used in very specific circumstances. Nothing will be blocked or logged in the Unified Audit if the action is performed by the process set to be excluded. No ThreatLocker policies will take effect on processes set to be excluded. When this field is omitted, no processes will be excluded. One or multiple exclusions can be added. As demonstrated in the Optional body section, each exclusion requires all of the fields listed below, except when exclusionType is set to 4. In this case, no file path can be specified; only the fields exclusionType and value should be used. If an excluded process is already applied to the group, it must be re-entered with each supporting field, either exactly as configured or with the desired changes, to keep the exclusion in effect. For additional information on excluding processes, see the KB article below:

Excluded Processes | ThreatLocker Help Center

• • • • exclusionType: This field determines the exclusion type that will be applied. This field expects the Integer associated with the exclusion type:

        • Execute = 1
        • Install = 2
        • Storage = 3
        • Network = 4
      • filePath: This field determines if a file path should also be matched with the entered excluded process. If you do not want to specify a file path for this process, you can leave this field as "". Be sure to use \\ instead of a single \ for the existing slashes in the path. Wildcards can be used in this field, as in the ThreatLocker Portal, as shown in this example: c:\\users\\*\\Documents\\*

        • Expects: Full file path or partial path with wildcards
      • value: This field determines the process that will be excluded. This field expects only a full process name, regardless of the directory (e.g., python.exe, code.exe). Wildcards cannot be used in this field.

        • Expects: Full process name as described above
    • initialMonitorModeHours: This field determines the initial Learning Mode period for the group. When this field is omitted, the initial Learning Mode period will be set to 0. This field expects the length of time to be entered in hours. For display purposes in the Portal, the hours entered into this field are converted to days and hours. The maximum number of hours that can be entered is 90,000 (3,750 days). When entering an Integer between 89,976 and 90,000, the group will be assigned an "Indefinite" Learning period. Anything less than 89,976 will set the Learning period accordingly. When the autoCreatePolicies field is not used, no policies will be created for this Learning period. If this field is omitted and a Learning Mode period is already assigned, it will be reset to 0. Any period entered here will overwrite the existing one.

      • Expects: Any non-negative Integer value up to and including 90,000

Note: The options applied to the group in the options field below should be used with extreme care as changing these options may greatly impact ThreatLocker's ability to monitor and secure your environment.

Options Tab: Choices and Descriptions | ThreatLocker Help Center

• • • options: 
      This field determines the options that will apply to the group. When this field is omitted, no options will be applied. One or multiple options can be entered into this field. For each option, enter the text of the option exactly as it appears in the KB article above. The Optional body section below demonstrates how to add four options. If an option is already applied to the group, it must be re-entered to keep it applied.

      • Expects: Text of any organization option exactly as listed in the article above
    • permitReplace: This field determines whether devices with the same hostname can reuse the same device record, inherit the same settings, and appear as one device on the Devices page for the group. When this field is omitted or set to false, this will not be allowed. When this field is set to true, this will be allowed. If this field is omitted and was previously set to true, it will revert to false, and each computer will have its own record in the Portal. For additional information, see the KB article below:

Deploying ThreatLocker in a VDI environment | ThreatLocker Help Center

• • • • Expects: true or false
    • policyRefreshIntervalSeconds: This field determines the Heartbeat Interval — how often the ThreatLocker Agent checks in to the Portal, in seconds — that will be assigned to the group. When this field is omitted, the Heartbeat Interval will be set to 60. The minimum number of seconds that can be entered is 8, and the maximum is 300 (5 minutes). If this field is omitted and a Heartbeat Interval is already assigned, it will be reset to 60. Any duration entered here will overwrite the existing one.
      • Expects: Any non-negative Integer value from 8 up to and including 300
    • tlInstructions: This field determines the Cyber Hero Management instructions that will be applied to the group. When this field is omitted, no instructions will be applied. This field should only be used when the cyberHeroUseOrgSettings field is omitted or set to false. If this field is omitted or left blank (null or " "), and there are instructions already applied to the group, they will be removed. Any instructions entered here will overwrite any existing ones.
      • Expects: Any text input

• Permission Requirements
  • Assign this permission: 
    • Edit Computer Groups

ComputerGroupUpdateForDelete

https://portalapi.INSTANCE.threatlocker.com/portalapi/ComputerGroup/ComputerGroupUpdateForDelete

• Method: POST
• Description: This API is used when navigating to the Assets icon and selecting the Groups page from the pop-out menu in the ThreatLocker Portal, locating and selecting the group(s) you wish to delete, and selecting the "Delete" button. This API is also used when navigating through the same Portal pages, selecting the trash can icon next to the group you wish to delete, and selecting "Yes" to confirm the deletion of the group. This API deletes Device Groups in your organization.

Currently, this API can only delete groups that are all within the same organization. Ensure each group selected is in that same organization.

• Required Body/Parameters
  • Fields

Note: Each of the following fields needs to be entered for each group you want to delete, as shown in the Required body section.

• • • computerGroupId: This field determines which group will be deleted. This field expects the computerGroupId of the group that will be deleted.

      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • organizationId: This field expects the organizationId of the organization in which the group that will be deleted exists. The organizationId should match the managedOrganizationId header used.

      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"

• Optional Body/Parameters
  • N/A
• Permission Requirements
  • Assign this permission:
    • Edit Computer Groups