Configure Darktrace

The Darktrace API provides a method of accessing additional information about a particular alert or device in the Darktrace system. The API uses HTTP GET requests to return formatted JSON data containing the requested information and HTTPPOST or DELETE requests to configure the system. The API can be an incredibly useful tool to integrate Darktrace with third-party SIEM or SOC environments, or perform bulk actions on devices and model breaches.

Prerequisites

• Darktrace Threat Visualizer login credentials.

Generate an API Token Pair

Before any data can be queried, an API token pair is needed for each master instance. Tokens can be generated on a per-user basis.

Generate a Per-User Token

To create a per-user token, a user must first be granted permission to access the API. API tokens can only be created by local users (those created within the Darktrace Threat Visualizer) and are not available to users created via LDAP or SAML SSO.

1. On the Threat Visualizer of the instance from which you wish to request data, click Menu and then click Admin.
2. Locate the desired user and click API Access in the Flags column.
3. Click Save.

4. As the user intended for API access, access the Threat Visualizer or SaaS Console.

   

   If already logged in, a logout/login is recommended to refresh the permissions.

5. Click Account Settings from the main menu.
6. Click the API Access button.

7. In the pop-up, click New.
   A Public and Private Token appear.

   

   The Private token will not be accessible once the window is closed. Copy this value for later. 

   Both tokens are required to generate the DT-API Signature value, which must be passed with every API request.

Important Considerations While Executing the Model Breaches API

• API Authentication requires the API request to be constructed in advance, as the specific request with its parameters is used to generate the authentication value [signature].
• The time value (starttime & endtime) used in request and signature must be same.
• Response data comes sorted in reverse chronological order (recent data first).
• Signature validity lasts for 30 minutes.
• By default, if there are no "start - end date" pairs specified, then data is fetched for the last year.
• The DT-API date (used in the header) should be within the limit of 30 minutes of the current UTC time.