Help CenterAPI Users allow administrators to create their own API authentication tokens and assign specific roles to them. This enables more automation and interaction with the ThreatLocker modules from outside the ThreatLocker Portal. Specifying roles that limit token permissions helps to ensure tokens can't be misused to authenticate with unauthorized APIs.
Before you create an API User, you will need to have at least one User Role created. For assistance with creating User Roles, please see the article below:
Creating API Users
Navigate to the Manage icon and select the Users -> API Users page from the pop-out menus in the ThreatLocker Portal.
Select the blue 'New API User' button in the top left corner.
The Create API User sidebar will slide out from the right. In the API Token Name input box, enter a name for the new token.
Select the authentication method. Either Basic Authentication (API Token) or OAuth 2.0 can be selected.
Using OAuth 2.0
Select OAuth 2.0. The Client ID and Client Secret will be revealed on Save.
In the Roles/Permissions section, you will specify the roles and organizations for which this token is valid.
Select a role in the Role dropdown, and an organization in the Organization dropdown, then press the blue '+' button to add the specified role/organization combination to the list. When adding a role without specifying which organization it applies to, it will be applied to all organizations.
The role name will be listed first with the organization name in parentheses. When the role applies to all organizations, only the role name will be listed, as shown below with the View Computers role.
Continue adding roles and organizations to provide this token with the permissions needed for the desired use case.
Select the 'View End User License Agreement on behalf of this API User' text to open and view the End User License Agreement. Once you have read through the agreement, select the checkbox next to Accept EULA to accept the agreement on behalf of the new API User.
Then, press the blue 'Create' button.
The OAuth 2.0 credentials will be displayed. The Client ID and Client Secret will only be shown once. When the close button is pressed, you will not be able to retrieve either again. Be sure to copy and securely save both the Client ID and Client Secret.
The new API User will now appear in the main grid with the organizationId where the API User was created appended to the token name, as shown below.
With your OAuth 2.0 credentials, call the Token PortalAPI endpoint, documentation linked below, and use the accessToken String value returned by the API call as your Bearer token.
/portalAPI/OAuth/* | ThreatLocker Help Center
Using Basic Authentication (API Token)
Select the 'Generate API Token' button to generate a token. This token will only be visible while the sidebar is open, so be sure to copy and save it securely before closing the sidebar.
Select an API Token Expiration. The token will renew the selected expiration time each time it is used. So, if 90 days is selected, the token will expire after 90 days of inactivity.
In the Roles/Permissions section, you will specify the roles and organizations for which this token is valid.
Select a role in the Role dropdown, and an organization in the Organization dropdown, then press the blue '+' button to add the specified role/organization combination to the list. When adding a role without specifying which organization it applies to, it will be applied to all organizations.
The role name will be listed first with the organization name in parentheses. When the role applies to all organizations, only the role name will be listed, as shown below with the View Computers role.
Continue adding roles and organizations to provide this token with the permissions needed for the desired use case.
Select the 'View End User License Agreement on behalf of this API User' text to open and view the End User License Agreement. Once you have read through the agreement, select the checkbox next to Accept EULA to accept the agreement on behalf of the new API User.
Then, press the blue 'Create' button.
The new API User will now appear in the main grid with the organizationId where the API User was created appended to the token name, as shown below.
Main Grid
- Multiselect box - Allows selecting multiple API Users at once and deleting them in bulk.
- API Token Name - Displays the name of all current tokens
- Created - Displays the date/time the API User Token was created
- Last Used - Displays the date/time the API User Token was last used
- Expires On - Displays the date/time the API Token will expire - This will always be blank for API Users created using OAuth 2.0 authentication.
- Actions - Displays the quick action icons listed below
- Reset API Token - Opens the sidebar to regenerate a new authentication token
-
- EULA Acceptance - Indicates whether the End User License Agreement has been accepted on behalf of the API User
-
- Delete API User - Deletes the API User on the same line
Locating API Documentation
If you are new to working with ThreatLocker PortalAPI endpoints and/or have questions regarding authentication and terminology you may see throughout the documentation, please look through the following guide:
Getting Started with ThreatLocker PortalAPIs
Documentation can be found by navigating to the Knowledge Base section linked below:
API Documentation | ThreatLocker Help Center
In addition to our Knowledge Base, from any page in the Portal, select the 'Help' button in the top-right corner, then select the 'API Documentation' menu item.
This will link to the ThreatLocker public Swagger page, which allows live testing and access to publicly available APIs.
