Connection and Configuration - Advanced Analytics API

We propose a REST API connection to the Advanced Analytics Data.

REST API

The API is documented here: OpenAPI. Organizations will need an API token to get access to their data. This token can be requested via your Customer Success Manager. The API operations require bearer authentication (also called token authentication) which is an HTTP authentication scheme that involves security tokens called bearer tokens.

Some of the parameters used in the API are explained here:

Parameter	Description
organization_name	Can be retrieved from the url of your AG5 environment. https://matrix.ag5.com/myorganization/main
repository_name	Can be retrieved from the url of your AG5 environment. https://matrix.ag5.com/myorganization/main
page_token	Used for pagination. Is returned in the response header (key = x-ag5-pagetoken)
page_size	Maximum number of records to return.
reference_time	For most events, this is treated as a ‘since’ and returns all records after this reference time. For EmploymentQualificationCompliance, only the events stored on the Day (Date) of the reference_time are returned.

The request header:

Key	Value
Authorization	Bearer <the provided token>
Accept	(optional) ‘text/csv’
Accept-Encoding	(optional) ‘gzip’

The responses can be retrieved in JSON or CSV format. JSON is default, CSV can be obtained by including the Accept header.

The API is again split up into Entities and Events. Note: the compliance calculations and the repository statistics can both be accessed via the Events endpoints.

For Entities, we advise you to start with the request to retrieve the entity-types:

/organizations/{organization_name}/repositories/{repository_name}/ entity-types. 

These entity types are required as a parameter in many of the other requests. Don’t forget to use the full name in your request:

seaspray.v<number>.<EntityType> 

For Events, we advise you to start with the request to retrieve the event-types.

/organizations/{organization_name}/repositories/{repository_name}/ event-types. 

Each event has both a type and a subject. But only for SIEM events a type can have multiple subjects. To illustrate this, the Compliance event has only one type:

seaspray.v1.GroupingCompliance

and one subject:

compliance_computation

Therefore the events can be retrieved by only referring to the event_type.

The SIEM events have one type but can have different subjects. For Siem events it is therefore advised to use both the event_type and event_subject to retrieve the events.

reference_time

By default, the events that were created after 00:00 am today (European standard time) are returned. The parameter reference_time can be used to specify the time in milliseconds since Jan 1, 1970 (Epoch or Unix timestamp) of the oldest event returned.

GroupingCompliance calculations are performed during the night. This could be before or after midnight. This may mean that a request without reference_time will return no events (because the last compliance calculation was done before 00:00 am today). Therefore we advise to use the reference_time parameter and make sure you retrieve the events of the last 24 hours.

For almost all Events, the events after the reference_time are returned, except for EmploymentQualificationCompliance events, for which only the events of one day (the date of the reference_time) are returned.

page_token

The returned entities and events are usually split into different pages based on the page_size. The page_token, to request the next page is returned in the response header.

Note, this response header is not visible in the OpenAPI - try it out functionality. If you use

CURL --verbose 

to call the endpoint in a terminal for example, the header will be visible.