This article will encompass a base for the calls that are related to processing only Application Control Approval Requests directly through our API endpoints.
Be sure to input the instance your organization exists on for each call. This is indicated with the "INSTANCE" text in each endpoint. Linked here is a KB to find your instance:
Locating Your Organization's Instance | ThreatLocker Help Center
Notes for this article: This article assumes all approval requests serviced through the ThreatLocker API are from the perspective of the currently managed Organization. The managed organization is the organization the ThreatLocker Portal is currently effectively displaying. The ID of the current managed organization can be verified though the URL of the web portal:
https://portal.threatlocker.com/<portal page>?mo=<managed organization ID>
Access to an organization, parent and child, is determined by the API user permissions defined in the Administrators page of the ThreatLocker Portal.
For more in-depth analysis of each of these endpoints, be sure to check out the other API documentation articles available here:
Getting Pending Approval Requests
ApprovalRequestGetByParameters
https://portalapi.INSTANCE.threatlocker.com/portalapi/ApprovalRequest/ApprovalRequestGetByParameters
If looking to view approval requests from a specific organization, take the organizationId and utilize it with the managedOrganizationId header. To get the organizationId easily, use the OrganizationGetChildrenIdsAndName endpoint. No additional parameters are needed for the OrganizationGetChildrenIdsAndName endpoint directly.
- In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
- Method: POST
- Description: This API will get a list of all the pending requests, including requests from Application Control, Elevation Control, and Storage Control, for your organization(s). If managing a parent organization, there is an option to show all the pending requests for all your child, including grandchild, organizations if looking to view/process their requests, too. This API will retrieve all the information needed relating to the approval request directly.
- Any valid integer can be entered for the pageNumber and pageSize fields and it will return in the selected formatting. For instance, if there are 5 pending requests to be returned but “pageNumber” : 1 and “pageSize” : 2, 2 entries will be returned per page and the first two requests will be returned.
- Body that will return the pending requests for just the currently managed organization
"isAscending": false,
"orderBy": "dateTime",
"pageNumber": 1,
"pageSize": 25,
"showChildOrganizations": false,
"showCurrentTierOnly": false,
"statusId": 1
- Body that will return the pending requests for the currently managed organization plus any child and grandchild organizations
"isAscending": false,
"orderBy": "dateTime",
"pageNumber": 1,
"pageSize": 25,
"showChildOrganizations": true,
"showCurrentTierOnly": false,
"statusId": 1
-
Listed below is a sample output from one request that is pending in an organization. The ID values have been replaced with 0's for display purposes and it can be expected that most of the values will be returned with a value and not just "". Values most pertinent to later API endpoints are in bold below:
{
- Permissions Needed for User
-
- Approve for Entire Organization
- Approve for Group
- Approve for Single Computer
- Approve for Single Computer Application Only
- View Approvals
- Elevation Administrator
Checking for Matching Applications
** Before approving a built-in application from a request, ensure that the file being permitted through the request is in accordance with the application you believe the request originated from. There are cases where common DLL and other files will be requested that can be used across multiple applications, causing the file to match into multiple applications. When applying a built-in, the entire built-in application is being effectively permitted. **
ApplicationGetMatchingList
https://portalapi.INSTANCE.threatlocker.com/portalapi/Application/ApplicationGetMatchingList
- Method: POST
- Description: This API will return a matching application when provided values that uniquely identify the requested file, such as it's ThreatLocker hash value, SHA256 hash value, or certificate name.
- Note: ThreatLocker recommends inputting one identifying value per call. Inputting multiple values, when all values may not align to the same unique application, may return multiple matching applications. For example, inputting the ThreatLocker hash value for the application "1pass", while simultaneously inputting the SHA256 hash value for the application "putty" will return matching application details for both 1pass and putty.
- Body to search for matching applications
- The following options can be used for the OSType in the below body:
- Windows = 1
- MAC = 2
- Linux = 3
- Windows XP = 5
- The following options can be used for the OSType in the below body:
- {
"hash": "<TLHash>",
"sha256": "<SHA256Hash>",
"path": "<String>",
"processPath": "<String>",
"organizationIds": null,
"certs": [
{
"sha": "<SHA256 of certificate>",
"subject": "<certificateName>",
"validCert": "<boolean>"
},
{
"sha": "<SHA256 of certificate>",
"subject": "<certificateName>",
"validCert": "<boolean>"
}
],
"createdBys": [
"<String>",
"<String>"
],
"osType": <Integer>
}
- Sample output of a matching application
- Permissions Needed for User
- Approve for Entire Organization
- Approve for Group
- Approve for Single Computer
- Approve for Single Computer Application Only
- View Approvals
Getting a custom application to add the requested file/rules into
ApplicationGetListForAddToApplication
https://portalapi.INSTANCE.threatlocker.com/portalapi/Application/ ApplicationGetListForAddToApplication
- Method: GET
- Description: This API will show all the applications available for use with the approval request, including parent organization applications available if viewing a request from a child organization. The parent applications will show in the "name" field when run in this format: "parentOrganizationName\\parentOrganizationApplicationName". The managedOrganizationId header can be used to show the results of searching available applications that can be applied to a request from a specific child organization. By default, all the Windows applications available will be shown with an OSType of 1. If you receive a request from a non-Windows machine, utilize the OSType parameter as shown below to search for the available applications to add into for the request. There is also an optional parameter for SearchText which allows you to narrow the search based on the application name.
- Parameters to search for existing custom applications
- In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
- OSType:
- Windows = 1
- MAC = 2
- Linux = 3
- Windows XP = 5
- SearchText: Expects an application name to be entered as text
- Listed below is a sample output from one application in an organization. The ID values have been replaced with 0 values for display purposes:
- The "name" output below will show the full name of the application, meaning that if the application exists at a parent organization, it will be displayed in the format: "parentOrganizationName\\parentOrganizationApplicationName". The "applicationName" will display just the name of the application itself without the parent nomenclature.
- Permissions Needed for User
- Edit Application Control Applications
Getting an Application to use when utilizing a Maintenance Mode
ApplicationGetForMaintenanceMode
https://portalapi.INSTANCE.threatlocker.com/portalapi/Application/ApplicationGetForMaintenanceMode
- Method: GET
- Description: When processing approval requests, there is an option to select an existing application and utilize a Maintenance Mode. With the selected application, the Maintenance Mode will temporarily capture or monitor files installed and executed in association with the initially requested file. This API will show all the applications available for use with a Maintenance Mode, including parent organization applications available if viewing a request from a child organization. The parent applications will show in the "label" field when run in this format: "parentOrganizationName\\parentOrganizationApplicationName". The managedOrganizationId header can be used to show the results from searching available applications. Those available applications can then be applied to a request from a specific child organization. By default, all the Windows applications available will be shown with an OSType of 1. If you receive a request from a non-Windows machine, utilize the OSType parameter as shown below to search for the available applications to add into for the request.
- Optional parameters
- In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
- OSType:
- Windows = 1
- MAC = 2
- Linux = 3
- Windows XP = 5
-
Permissions Needed for User
- Edit Computers
- Edit Application Control Applications
ApplicationGetResearchDetailsById
https://portalapi.INSTANCE.threatlocker.com/portalapi/Application/ApplicationGetResearchDetailsById
This call is purely optional, but is useful for gaining additional information about an application being requested or potentially being added into depending on which applicationId is supplied.
- Method: GET
- Description: This API will get any research data that is available for the applicationId provided. This research data includes a product description, the potential risks of the application, and a mitigation strategy to limit the risk of this application in your organization(s).
- Required parameters
- applicationId: This is the Unique Identifier for the application you would like to review the research data for. Only one applicationId can be entered/reviewed at one time.
- Expects a GUID in format: "00000000-0000-0000-0000-000000000000"
- applicationId: This is the Unique Identifier for the application you would like to review the research data for. Only one applicationId can be entered/reviewed at one time.
- Permissions Needed for User
- Edit Application Control Applications
- Approve for Entire Organization
- Approve for Group
- Approve for Single Computer
- Approve for Single Computer Application Only
- View Approvals
Approving the Request
ApprovalRequestGetPermitApplicationById
https://portalapi.INSTANCE.threatlocker.com/portalapi/ApprovalRequest/ApprovalRequestGetPermitApplicationById
- Method: GET
- Description: This API will show all the details/Ids of an approval request, including the formatted json field that is needed to utilize the ApprovalRequestPermitApplication endpoint below. Be sure to utilize the same managedOrganizationId as the organizationId where the approval request exists.
- Required parameters
- approvalRequestId: <GUID> in format "00000000-0000-0000-0000-000000000000"
- Optional parameters
- In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
- Permissions Needed for User
- Approve for Entire Organization
- Approve for Group
- Approve for Single Computer
- Approve for Single Computer Application Only
- View Approvals
ApprovalRequestPermitApplication
https://portalapi.INSTANCE.threatlocker.com/portalapi/ApprovalRequest/ApprovalRequestPermitApplication
Be sure to input the instance your organization is on in the "userinstance" field for each body. Values changed in each body are in bold below.
- Method: POST
- Description: This API will process pending approval requests. The organizationIds list expects the organizationId of any parent organizations effectively "above" where the approval request originated from. The json value can be imported/copied over from the endpoint listed above (ApprovalRequestGetPermitApplicationById) for processing purposes. Be sure to utilize the same managedOrganizationId as the organizationId where the approval request exists.
- Maintenance Modes that can be used when processing an approval request
- RuleIds:
- 0 = No Maintenance Mode activated, manual rules
- 1 = Enable Installation Mode for one hour
- 2 = Enable Learning Mode for one hour
- 3 = Enable Monitor Mode for one hour
- RuleIds:
- Configuring the policy level when creating a new policy
Note: Before looking to create a new policy, be sure "useExistingPolicy" in the "policyConditions" field is set to false.
-
- If looking to permit for a computer group, use the ComputerGroupGetForPermitApplication endpoint to get a list of all the computer groups available to use when permitting for the group, passing in one of the OSTypes below that correspond to the approval request as a parameter. When processing a request from a child organization, utilize the managedOrganizationId header to show all the groups available to the specific child organization.
- OSType:
- Windows = 1
- MAC = 2
- Linux = 3
- Windows XP = 5
- In header: "managedOrganizationId": <GUID> in format "00000000-0000-0000-0000-000000000000"
- OSType:
- If looking to permit for a computer group, use the ComputerGroupGetForPermitApplication endpoint to get a list of all the computer groups available to use when permitting for the group, passing in one of the OSTypes below that correspond to the approval request as a parameter. When processing a request from a child organization, utilize the managedOrganizationId header to show all the groups available to the specific child organization.
-
- The below selections are all inside the "policyLevel" field listed below in the Approval Bodies section
-
-
- "toEntireOrganization": Set this to true to create a new entire organization policy, otherwise set to false.
- "toComputerGroup": Set this to true to create a new computer group policy as per the settings configured in the "selectedComputerGroup" field below, otherwise set to false. Fill in the computerGroupId and name fields with the Id and name of the group and the organizationId and organizationName fields with the Id and name of the organization where the group exists.
-
-
-
- "toComputer": Set this to true to create a new computer level policy affecting the requesting computer, otherwise set to false.
-
- Approval Bodies
- Body to make a new application, use Learning Mode for one hour, and create a new policy for the computer
-
- Body to approve using an existing application, applying a custom rule by path and certificate, and using an existing policy
{
-
- Body to approve a matching application and create a new policy affecting the entire organization
-
Permissions Needed for User
- Approve for Entire Organization
- Approve for Group
- Approve for Single Computer
- Approve for Single Computer Application Only