ThreatLocker Approval Requests
approval_requestsQuery and manage ThreatLocker approval requests created when users request access to blocked software. List, review, approve, reject, or ignore pending requests and generate policies.
Instructions
Query ThreatLocker approval requests.
When users encounter blocked software and request access, it creates an approval request. Admins review these requests to decide whether to permit the software by creating policies.
Common workflows:
List pending requests: action=list, statusId=1
Get pending request count: action=count
Find requests for a specific user: action=list, searchText="username"
Get request details: action=get, approvalRequestId="..."
Get file info for download/analysis: action=get_file_download_details, approvalRequestId="..."
Get permit options (apps, groups): action=get_permit_application, approvalRequestId="..."
Get storage request details: action=get_storage_approval, approvalRequestId="..."
Approve a request: action=permit. Two-step — call get_permit_application first, round-trip its opaque "json" blob into permitJson, then pick permitMode + policyLevel. Payload-verified, NOT live-tested: validate in a non-prod org before relying on it.
Request statuses: 1=Pending (needs review), 4=Approved, 6=Not Learned (learning mode), 10=Ignored, 12=Added to Application, 13=Escalated (from Cyber Heroes), 16=Self-Approved
Pitfalls:
list defaults to newest-first (isAscending=false) — the right default for triaging the pending queue.
Permitting a request is a two-step flow: call get_permit_application first and round-trip its opaque "json" blob; don't synthesize it.
Before approving a Built-In matching app, confirm the file isn't a shared DLL matching unrelated apps (you'd permit the whole built-in).
Permissions: View Approvals, Approve for Entire Organization/Group/Single Computer. Pagination: list action is paginated (use fetchAllPages=true to auto-fetch all pages). Key response fields: approvalRequestId, username, fullPath, actionType, statusId, computerName, requestDateTime.
Related tools: action_log (see the deny event), applications (find matching apps), policies (create permits)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | list=search requests, get=single request details, count=pending count, get_file_download_details=file download info, get_permit_application=permit options, get_storage_approval=storage request details, reject=reject a pending request with a reason, take_ownership=assign a request to yourself, permit=approve an application request (round-trip the opaque json blob), ignore=ignore a request, permit_storage=approve a storage/USB request (round-trip get_storage_approval json), get_testing_environment=file/testing-env details for a request | |
| osType | No | permit: 1=Windows, 2=macOS, 3=Linux, 5=Windows XP. | |
| ruleId | No | permit: 0=manual rules, 1=Installation Mode 1hr, 2=Learning Mode 1hr, 3=Monitor Mode 1hr. | |
| orderBy | No | Field to order by (default: datetime) | |
| comments | No | permit: comment on the request. NOTE: overwrites any existing comment if provided. | |
| fullPath | No | permit: file path of the requested file (use \\ for backslashes). | |
| pageSize | No | Results per page (default: 25, max: 500) | |
| statusId | No | Filter by status: 1=Pending (default for list), 4=Approved, 6=Not Learned, 10=Ignored, 12=Added to Application, 13=Escalated, 16=Self-Approved | |
| ticketId | No | permit: ticket id. NOTE: overwrites existing value if provided. | |
| computerId | No | permit: requesting computer GUID. | |
| entityType | No | permit_storage: scope level for a new policy (0=computer, 1=group, 2=org). | |
| pageNumber | No | Page number (default: 1) | |
| permitJson | No | permit: the opaque "json" blob from get_permit_application, passed back VERBATIM. Do not synthesize or edit it. | |
| permitMode | No | permit: existing_app=add file rule to an existing application; matching_app=use a ThreatLocker-matched application; new_app=create a new application. Requires applicationId+applicationName (existing/matching) or newApplicationName (new). | |
| policyName | No | permit_storage: name for the new storage policy (required for storageMode=new_policy). | |
| searchText | No | Filter by text | |
| appliesToId | No | permit_storage: entity GUID the new policy applies to. | |
| isAscending | No | Sort ascending. Default: false (newest-first), the right default for triaging the pending queue. | |
| policyLevel | No | permit: scope the resulting policy to the entire organization, the computer group, or just the requesting computer. | |
| storageJson | No | permit_storage: the opaque "json" blob from get_storage_approval, passed back VERBATIM. | |
| storageMode | No | permit_storage: add_to_existing=attach the device to an existing storage policy (needs storagePolicyId); new_policy=create a new storage policy (needs policyName). | |
| allFilePaths | No | permit_storage: permit all file paths on the device (default: false); otherwise set selectedPath. | |
| ignoreReason | No | Reason shown to the requestor when ignoring (ignore action). | |
| rejectReason | No | Reason shown to the requestor when rejecting (reject action). | |
| selectedPath | No | permit_storage: specific path to permit when allFilePaths=false. | |
| applicationId | No | permit: application GUID (required for permitMode existing_app/matching_app). | |
| fetchAllPages | No | Fetch all pages automatically (max 10 pages). Default: false (single page). | |
| ignoreSubject | No | Optional response email subject for ignore. | |
| manualOptions | No | permit: file-rule conditions. A hash rule = { "hash": "..." } and NOTHING else. A property rule = any of { fullPath, cert, processPath, createdBy } (pair at least two for a stronger rule). | |
| sourceTableId | No | get_testing_environment: source log table (1=ActionLog, 2=DenyActionLog, 3=Baseline, 4=EventLog; default 2). | |
| expirationDate | No | permit_storage: approval expiry in UTC (YYYY-MM-DDTHH:MM:SSZ). | |
| notifyOnIgnore | No | Email the requestor on ignore (default: false). | |
| organizationId | No | permit: organization GUID of the request. | |
| responseReason | No | Optional response email body for reject. | |
| applicationName | No | permit: application name (required for permitMode existing_app/matching_app). | |
| computerGroupId | No | permit: computer group GUID (used as selectedComputerGroup when policyLevel=computer_group). | |
| elevationStatus | No | permit: 0=do not elevate, 1=elevate, 2=silent elevation (only with the Elevation product). | |
| organizationIds | No | permit: parent-hierarchy GUID chain (child→…→root); usually 1 entry for a child-org request. | |
| responseSubject | No | Optional response email subject for reject. | |
| response_format | No | Output format: markdown (default, human-readable) or json (structured) | markdown |
| storagePolicyId | No | permit_storage: existing storage policy GUID (required for storageMode=add_to_existing). | |
| notifyOnResponse | No | Email the requestor on response (reject/permit_storage; default: false). | |
| allStorageDevices | No | permit_storage: apply to all storage devices (default: false). | |
| approvalRequestId | No | Approval request GUID (required for get, get_file_download_details, get_permit_application, get_storage_approval). Find via list action first. | |
| networkExclusions | No | permit: network exclusions applied to the resulting ringfence permit. | |
| ringfenceActionId | No | permit: ringfence action id applied to the permit. | |
| useExistingPolicy | No | permit: update an existing policy affecting the computer instead of creating one (default false). | |
| newApplicationName | No | permit: name for the new application (required for permitMode new_app). | |
| elevationExpiration | No | permit: elevation expiry in hours (used when elevationStatus>0). | |
| showCurrentTierOnly | No | Only show requests at the current approval tier (multi-tier/MSP escalation; default: false) | |
| policyExpirationDate | No | permit: expiry for the created policy in UTC (YYYY-MM-DDTHH:MM:SSZ). | |
| requestorEmailAddress | No | permit: requestor email. NOTE: overwrites existing value if provided. | |
| ticketApprovalManager | No | permit: approval manager. NOTE: overwrites existing value if provided. | |
| showChildOrganizations | No | Include child organizations (default: false) | |
| applicationOrganizationId | No | permit: organization GUID that owns the application (defaults to organizationId). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Response data — shape varies by action | |
| error | No | ||
| success | Yes | ||
| pagination | No |