Skip to main content

Bulk Whitelisting API Guide

Disclaimer

This document contains confidential information from Bugsmirror Research Pvt. Ltd. By accessing this document you agree to keep the information in strict confidence. Do not copy, disclose, or distribute it without proper authorisation or written consent from Bugsmirror Research Pvt. Ltd. If you are not the intended recipient, please delete or shred all the copies of the document with you and inform the sender immediately. Be aware that any unauthorised disclosure, copying, or distribution of the contents of this document is strictly prohibited.

1. Introduction​

Welcome to the ThreatLens Whitelisting API Guide. Our system provides a robust interface for organizations to programmatically manage their security posture. The whitelisting API allows your engineering and security teams to safely bypass, update, or completely unwhitelist specific threat IDs for a designated list of devices in real-time.

2. Architecture & Flow​

The whitelisting lifecycle operates through a synchronous API call:

  • Request: Your application dispatches an HTTPS POST request containing the target devices and threat IDs to the ThreatLens Whitelist API.
  • Validation: ThreatLens authenticates your organization and verifies your active billing plan.
  • Execution: Our system concurrently updates the threat intelligence profiles for the specified devices in our datastores.
  • Response: API immediately returns an HTTP status code indicating the success or failure of the mass update.

3. API Endpoint Requirements​

To successfully integrate with the whitelisting capability, your systems must interact with the endpoint using the following technical specifications:

  • Path: /whitelist (Note: The Base URL will be shared separately by the ThreatLens integration team).
  • HTTP Method: POST
  • Rate Limit: 100 requests per second (RPS) per organization. Exceeding this limit will result in rate-limiting errors.
  • Billing: Utilizing this API incurs a cost of 100 Cloud Credits per 1,000,000 (1 Million) API calls.

4. Request Headers​

Every request dispatched to the whitelisting API must include the following standardized headers for content parsing and authentication.

HeaderTypeDescription
Content-TypeStringMust be set to application/json.
AuthorizationStringYour active Organization Authorization Token used to verify identity and billing status.

5. Request Payload Schema​

The whitelisting instructions must be delivered in the body of the POST request as a JSON object.

Important Constraints:​

  • Uniform Application: The exact array of ThreatIds provided in the payload will be uniformly applied to all devices listed in the DeviceIds array. You cannot whitelist different threats for different devices within a single API call.
  • Unwhitelisting: To remove or clear all whitelisted threats from the specified devices, pass an empty array ([]) for the ThreatIds field.

Schema Definition​

FieldTypeDescription
DeviceIdsArray of StringsA list of unique identifiers for the devices to be updated. Maximum limit: 100 devices per request.
ThreatIdsArray of StringsA list of the specific threat IDs you wish to whitelist. Pass an empty array [] to unwhitelist all threats. Note: Threat IDs must be valid as shown in your ThreatLens dashboard. As Threat IDs can change or be updated, please regularly consult your dashboard to ensure you are using the most current identifiers.

Example JSON Payload (Whitelisting)​

{
  "DeviceIds": [
    "device-id-alpha-882",
    "device-id-beta-911"
  ],
  "ThreatIds": [
    "61007",
    "00000"
  ]
}

Example JSON Payload (Unwhitelisting)​

{
  "DeviceIds": [
    "device-id-alpha-882",
    "device-id-beta-911"
  ],
  "ThreatIds": []
}

6. Response Codes & Error Handling​

Your system should be prepared to handle the following HTTP status codes returned by the API.

Status CodeDescriptionReason
200 OKSuccessThe devices were successfully updated with the provided threat configurations.
400 Bad RequestValidation ErrorPayload is malformed, the active plan is expired, or the devices belong to a mismatched organization.
401 UnauthorizedAuth ErrorThe Authorization token is missing, invalid, or has expired.
405 Method Not AllowedRouting ErrorThe endpoint was called with an HTTP method other than POST.
500 Internal Server ErrorServer ErrorThreatLens encountered an internal database or processing error.

7. Example cURL Request​

You can use the following cURL command to simulate a whitelisting API request and test the integration locally:

curl -X POST <BASE_URL>/whitelist \
  -H "Content-Type: application/json" \
  -H "Authorization: <your-organization-auth-token>" \
  -d '{
    "DeviceIds": ["device-id-alpha-882", "device-id-beta-911"],
    "ThreatIds": ["61007", "00000"]
  }'

8. Implementation Checklist​

Please run through this checklist before moving your API integration to production:

  • Configure your client to point to the correct Base URL (provided separately) and the /whitelist path.
  • Ensure your client application makes requests exclusively via HTTPS.
  • Set the HTTP method strictly to POST.
  • Include the valid Authorization token in the request headers.
  • Format the request body as valid JSON.
  • Implement logic to handle unwhitelisting by passing an empty ThreatIds array.
  • Implement logic to handle the 100 requests per second rate limit gracefully (e.g., client-side queuing or backoff).
  • Implement error handling for 4xx and 5xx HTTP response codes.
Last updated on