(Advanced Settings) - /portalAPI/AgentSetting/*

This article will encompass all PortalAPI calls that are related to /portalAPI/AgentSetting/* 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

AgentSettingGetById

https://portalapi.INSTANCE.threatlocker.com/portalapi/AgentSetting/AgentSettingGetById

• Method: GET
• Description: This API is used when selecting the flask and gear icon in the top-right corner of any page in the ThreatLocker Portal and selecting an Advanced Setting to view its details. This API returns detailed information about the selected Advanced Setting, including, but not limited to, whether the setting is enabled, where it applies, and its parameters. Ensure that the managedOrganizationId header you use matches the location where the setting exists.

Below are the most relevant fields returned in the response body by this API:

• appliesToId: This field returns the ID of the location where the Advanced Setting is currently applied, either an organizationId, a computerGroupId, or a computerId.
• appliesToTypeId: This field returns the level at which the Advanced Setting is applied, either the global, global group, entire organization, computer group, or computer level. Listed below are the corresponding Integer values:
  • Entire organization = 1
  • Global OR global group OR computer group level = 2
  • Computer level = 3
• parameters: This field returns a list of the configurations of the Advanced Setting. Each definition returned in the list is either a setting that can be configured or information about the Advanced Setting.
• osTypes: This field returns the operating systems the Advanced Setting can be applied to, which might not match where it is currently applied. Review the OS Type of the appliesToId to determine where the Advanced Setting is applied. Listed below are the different OS Types that can be returned:
  • Windows = 1
  • Mac = 2
  • Linux = 3
  • Windows XP = 5
  • Ingester = 6
  • Portal = 8

• Required Body/Parameters
  • Parameters
    • agentSettingId: This field determines which setting's information will be returned. To get a list of agentSettingIds, use the AgentSettingGetByParameters API.
      • Expects: Any non-negative Integer value
• Optional Body/Parameters
  • N/A
• Permission Requirements
  • Assign any one of the following permissions:
    • Edit Advanced Settings
    • View Advanced Settings

AgentSettingGetByParameters

https://portalapi.INSTANCE.threatlocker.com/portalapi/AgentSetting/AgentSettingGetByParameters

• Method: POST
• Description: This API is used when selecting the flask and gear icon in the top-right corner of any page in the ThreatLocker Portal. This API returns all your Advanced Settings based on the fields you select. Ensure that the managedOrganizationId you use matches the location where you want to view your Advanced Settings.

Be sure to review the Optional Body/Parameters section before beginning to use this API to ensure accurate settings are returned for your search. Many of the fields listed are not required in the call to this API, but omitting them may affect your results.

• Required Body/Parameters
  • Fields
    • pageNumber and pageSize: These fields determine how many settings will be returned, as if the response were on the Advanced Settings page. However, these fields do not follow the same conventions for pageNumber and pageSize as the Portal does (the Portal uses 25, 50, or 100 for pageSize). Any valid integer can be entered, and the results will be returned in the selected format. For instance, if there are 5 settings to be returned but "pageNumber": 1 and "pageSize": 2, 2 entries will be returned per page, and the first two settings will be shown.

      • Expects: An Integer value

• Optional Body/Parameters
  • Fields
    • appliesToId: This field determines the scope of the settings that will be returned. When "00000000-0000-0000-0000-000000000000" or this field is omitted, all settings from all organizations, computer groups, and computers will be shown based on the other search fields. When an ID is entered into this field, the search will be narrowed to that specific ID (location). Any valid organizationId, computerGroupId, or computerId can be entered. When applicable, ensure the selected ID is within the managedOrganizationId used in the header.
      • Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
    • includeChildren: This field determines whether settings from your child organizations will be returned. When this field is omitted or set to false, only settings from the currently entered managedOrganizationId will be returned. When this field is set to true, all child organization settings, including those of grandchild organizations, will be returned.
      • Expects: true or false
    • osType: This field determines the OS Type to which the settings are supported/can be applied. Note that this does not indicate which OS Type the setting actually applies to, only where it is supported/can be applied. Review the appliesToId and organizationId fields in the API response for each setting to correctly determine where each setting is applied. When this field is omitted, the API will default to "All", and settings from any OS Type will be returned. This field expects the Integer associated with the OS Type:
      • All = 0
      • Windows = 1
      • Mac = 2
      • Linux = 4
      • Windows XP = 16
      • Ingester = 32
      • Portal = 64
    • searchText: This field allows you to search/narrow the settings returned by inputting any text/details you want to search for. When this field is omitted, all settings will be returned based on the other search fields. When text is entered into this field, it searches for results by setting name only. This field searches case-insensitively and effectively uses wildcards on either side of the entered text. For example, entering "App" into this field will return any setting whose name contains "App".
      • Expects: Any text input
    • showAll: This field is used when an appliesToId value other than "00000000-0000-0000-0000-000000000000" is used. When this field is omitted or set to false, only settings at the specified appliesToId will be shown. When this field is set to true, it shows any settings that affect the currently selected level. This means that if a computerId is entered into the appliesToId field, any settings that apply at the global, global group, entire organization, and computer group levels will be displayed, in addition to the settings at the computer level. This is because the computer may have settings at these levels that could affect it as well.
      
      • Expects: true or false

• Permission Requirements
  
  • Assign any one of the following permissions:
    • Edit Advanced Settings
    • View Advanced Settings