Authentication

Authentication of the API endpoint is secured using Verimatrix platformAPI keys. These API keys can be generated in the Verimatrix portal,under Settings → API Key Manager.

The API keys are exchanged for a short-lived access token, which in turn is used when calling the Verimatrix XTD SIEM API.

Using Access Tokens

Once an access token has been obtained, it is passed to the Verimatrix APIs using an 'Authorization' header, with the value being the access token in question.

GET /v2/siem/detections
...
Authorization: <access token>

Basic Request

Basic requests are made to the SIEM API URL using a GET request.

The accept header indicates which response format is requested:

GET /v2/siem/detections
Accept: application/json
...

{
  // Response body
}

Filtering

The API provides filtering capabilities to reduce the response data returned to the caller. All parameters are currently passed to the API as query parameters (on the URL).

Parameter	Format	Usage
riskLevel	LOW \| SUSPICIOUS \| HIGH	Filters all detections by the risk level associated with them
limit	Positive integers between 10 and 1000	Limits the number of records returned from the API
from	Positive integer (timestamp in ms)	Include only records created after the specified date
to	Positive integer (timestamp in ms)	Include only records created before the specified date
cursor	A valid string from a previous response	Reference cursor for making multiple requests

Filtering Example

The following example filters out the results to include only detections which have been deemed high risk.

GET /v2/siem/detections?riskLevel=HIGH
Accept: application/json
...

{
  // Response body
}

Data Polling

To ensure timely consumption of SIEM data, call the SIEM API in a polling fashion.

In addition to polling the data regularly, with set to/from filtering, the API may at times return more data than can fit in the response (more than the limit specified or the max limit allowed by the API). In those cases, the API will return 'pagination' information, allowing the caller to retrieve all the data for that interval.

Data De-duplication

There is a chance that the data retrieval has overlaps in the data set returned and that some de-duplication may be necessary. The identifier of the detection can be used for this as it is a unique property of the detection.

Rate Limits

Rate limits exist on the API and are enforced if significant amounts of requests are deemed to break those limits. However, the typical usage of the API is a low-rate, long-running poll and it should not be affected by rate limiting.

API Documentation

OpenAPI specifications for the APIs are available in the integration documentation bundle. The latest version of this can always be retrieved using an authenticated GET request to '/v2/openapi'.

GET /v2/openapi
...
{
  // OpenAPI documentation
}