ThreatLocker API Patterns

ThreatLocker MCP Tools & API Patterns

Overview

The ThreatLocker MCP server wraps the ThreatLocker Portal API (https://portalapi.g.threatlocker.com/portalapi) and exposes tools across computers, computer groups, approval requests, audit log ("Action Log" in the UI), and organizations. The API has two quirks that surprise people: the auth header does NOT use Bearer, and most "list" endpoints are POSTs against /Entity/EntityGetByParameters with a structured body — not GETs with query strings.

Anti-triggers

• Enumerating or pivoting between tenants. This skill explains the organizationId header and the childOrganizations flag; the tools that actually list children, fetch auth keys, and resolve move targets are threatlocker-organizations.
• Reading or storing an organization's auth key. The header mechanics are here, but the tool that returns a live credential is in threatlocker-organizations — treat its output as a secret.

Connection & Authentication

Raw API Key Header

ThreatLocker authenticates with a raw API key — no Bearer prefix:

Common mistake: Sending Authorization: Bearer <key> returns 401. Send the key bare.

Environment Variables

export THREATLOCKER_API_KEY="your-raw-api-key"
export THREATLOCKER_BASE_URL="https://portalapi.g.threatlocker.com/portalapi"

Multi-Tenant Routing

ThreatLocker is built for MSPs and uses organizations as the tenant boundary. Three patterns:

1. Default org — Omit the organizationId header. The API uses the API key's primary organization.
2. Specific child org — Set organizationId to a child org ID to scope a single call to that tenant.
3. Fleet-wide fan-out — Set the body flag childOrganizations: true on *GetByParameters endpoints to roll up data across all child organizations the API key can see.

For tenant pivots, see the organizations skill.

Available MCP Tools

Computers

Computer Groups

Approval Requests

Audit Log (Action Log)

Organizations

POST-Based "GetByParameters" Pattern

Most list endpoints are POST /Entity/EntityGetByParameters with a JSON body. Request shape:

{
  "pageNumber": 1,
  "pageSize": 50,
  "isAscending": false,
  "orderBy": "lastCheckin",
  "searchText": "",
  "childOrganizations": false
}

Response shape:

{
  "totalItems": 1284,
  "items": [ /* array of entities */ ]
}

Pagination

ThreatLocker uses page numbers, not cursors:

1. Call with pageNumber: 1, pageSize: 50 (or 100/200).
2. Compute totalPages = ceil(totalItems / pageSize).
3. Continue until you have collected totalItems rows or reached the last page.

Avoid huge pageSize values — large pages can time out. 50–200 is the sweet spot.

Sort and Search

• orderBy is an entity-specific column name (e.g. lastCheckin, computerName).
• isAscending toggles direction.
• searchText is a substring match across the entity's searchable columns (computer name, hostname, OS, etc.).

Error Handling

Best Practices

• Default to pageSize: 100 and paginate; always check totalItems before assuming you have the full set.
• For multi-tenant reports, fan out with childOrganizations: true rather than looping per-org when the entity supports it.
• Cache the result of threatlocker_organizations_list_children — child org lists rarely change within a session.
• Always pass organizationId explicitly when generating client-facing reports so the source tenant is unambiguous.

Related Skills

• computers — Endpoint inventory
• computer-groups — Policy scoping
• approval-requests — Application approvals
• audit-log — Action Log investigation
• organizations — Multi-tenant pivots