Getting Started with ThreatLocker PortalAPIs

This article serves as an introductory guide for setting up and using ThreatLocker PortalAPI endpoints. This article is designed for ThreatLocker Administrators that have some experience working with APIs already and are looking to maximize what they can do through automation and/or without having to access the ThreatLocker Portal directly.

Prerequisities

• Locate the instance where your organization exists. See the Instance section below for more information on getting your organization's instance.
• At least one valid ThreatLocker API User token with at least one User Role applied. Linked below is more information on creating API Users:

API Users | ThreatLocker Help Center

• Identify the organization(s) you'll be calling the ThreatLocker PortalAPI for, and have their IDs ready to use in the managedOrganizationId header. See the ManagedOrganizationId section below for more information.
• Postman/Talend/Any agent that can be used to call PortalAPI endpoints. Throughout this article, only Postman will be used.
• Basic knowledge of ThreatLocker products, permissions, and the functionalities/actions that can be taken both from the Portal and on the Agent using ThreatLocker.

Instance

In the PortalAPI Documentation articles, each PortalAPI endpoint will have its URL listed directly below its name, as shown in the screenshot below. Replace the "INSTANCE" text with the instance letter found following the instructions below.

In the examples listed throughout this article, all PortalAPI calls are made to an organization on instance "B", as shown by "...portalapi.B.threatlocker.com...". Unless your organization is on instance "B", replace "B" in all your PortalAPI calls with the instance letter for the instance where your organization exists. Linked below is more information on locating your organization's instance:

Locating Your Organization's Instance | ThreatLocker Help Center

Authentication

For each call, the ThreatLocker PortalAPI expects the API User's authentication token to be appended to the header of each request. The token should be set up with an auth type of "API Key". The key name should always be "Authorization", and the value should always be the valid API User token. Shown below is how to do this in Postman in the Authorization tab.

In the examples throughout this article, the authentication token is configured in the Authorization tab so that it will be automatically appended to the request header when the request is sent. However, you can also manually append this token to the header of each request, as shown below.

ManagedOrganizationId

In addition to appending the Authorization token to each request header, the PortalAPI also expects the organizationId to which it will create, read, update, or delete organization data. To get the organizationId values, navigate to the Manage icon and select the Organizations page from the pop-out menu in the ThreatLocker Portal. From there, select the settings icon in the Actions column to open the organization sidebar, and copy/save the GUID below the "Organization ID" heading.

For each PortalAPI request, append a header named "managedOrganizationId" with the desired organizationId in the value field, as shown below. This header can change where the data is created, returned, modified, or deleted, and using the wrong organizationId may cause the call to fail. Think of it as selecting a different organization in the ThreatLocker Portal when changing the managedOrganizationId header value.

Permissioning

The permissions required to call each PortalAPI endpoint are listed in the Permission Requirements section below each endpoint in the respective PortalAPI Documentation article. Ensure that permissions are assigned to the User Role corresponding to the API User being used, and that the role has only the permissions needed to call the desired endpoints, thereby applying the principle of Zero Trust to your API User.

It is important to pay attention to how the Permission Requirements section is structured in each article, as some endpoints require one of the following permissions, while others require a specific combination of permissions, as shown in the two screenshots below.

Sample GET Request

For this example, the ThreatLocker PortalAPI endpoint ApplicationGetResearchDetailsById will be called. Full documentation for this endpoint is available here:

ApplicationGetResearchDetailsById

For this endpoint, the managedOrganizationId can be set to any valid organizationId that the API User has access to. As per the documentation listed, any one of the following permissions is required. For this example, just the "View Application Control Applications" permission has been assigned to the API User.

• Approve for Entire Organization
• Approve for Entire Organization (Hash Only)
• Approve for Group
• Approve for Group (Hash Only)
• Approve for Single Computer
• Approve for Single Computer (Application Only)
• Approve for Single Computer (Hash Only)
• Edit Application Control Applications
• View Application Control Applications
• View Approvals

As per the documentation listed above, this endpoint requires the applicationId parameter with a valid GUID (applicationId) entered into the value field. For this example, the applicationId GUID corresponds to the Windows ThreatLocker Built-In application for Adobe Acrobat and is listed in the Request URL dropdown below.

If the call is successful using the applicationId above, the following response body in the dropdown below will be returned.

Sample POST Request

For this example, the ThreatLocker PortalAPI endpoint ComputerGroupGetByParameters will be called. The PortalAPI Documentation articles break down POST requests into the required versus optional fields. Only the required fields/body are needed to successfully call the endpoint. However, look for additional notes on limited functionality or potential unintended behavior when fields are omitted. Full documentation for the endpoint used in this example is available here:

ComputerGroupGetByParameters

For this endpoint, the managedOrganizationId can be set to any valid organizationId that the API User has access to. Remember that when changing the managedOrganizationId, the results returned by the PortalAPI will appear as if you are navigating to different organizations' Computer Groups pages in the ThreatLocker Portal.

As per the documentation listed, any one of the following permissions is required. For this example, just the "View Computer Groups" permission has been assigned to the API User.

• Edit Computer Groups
• Install Computers
• View Computer Groups

As per the documentation above, this endpoint requires, at a minimum, the following JSON body in the PortalAPI request.

For this example, the following JSON body, including all optional fields, will be used.

If the call is successful using one of the JSON bodies above, the following JSON response body in the dropdown below will be returned. 3 computer groups were returned for this example. Note: Sensitive values have been removed and replaced with placeholders, noted with <> characters around them, and 0 values. You can expect these values to contain valid data when returned from the PortalAPI.

Common Errors/Troubleshooting