Audit Trail API
From SpinetiX Support Wiki
Summary information and/or updates to the documentation can be found on this page.
Introduction
The Audit Trail API is used to view and download audit trail reports from the SpinetiX Cloud that provides evidence of all user actions within a SpinetiX ARYA™ account. The API makes them available in machine-friendly JSON and CSV formats, which can be further processed by a third-party system for monitoring purposes for instance, or manually inspected after a security incident.
This API is available to all SpinetiX ARYA™ Enterprise accounts.
The audit trail data is kept for three months. if a longer archival period is needed, it is recommended that the audit trail data be downloaded periodically and preserved.
Overview
The Audit Trail API offers access to SpinetiX Cloud's user actions audit trail logs via authenticated HTTPS calls to the dedicated /group/user-actions
endpoint.
Recorded audit trail events are retrieved by sending a GET request to that endpoint, passing the authentication, format and filtering parameters in the query string.
Supported formats
Each event in the audit trail may have information attached such as the list of affected resources and changes, the structure of which depends on the event type.
The returned audit trail data can be returned as JSON or as a CSV (comma separated values) table.
When JSON is selected as the return format, the complete event data is returned as JSON can naturally represent the structured data. When the CSV format is selected only top-level fields are returned due to the tabular nature of CSV. Each event has an array of information attached to it, when that array has multiple elements they will be returned in a single CSV column as a comma separated string.
Examples
Request with action filler
Sample request:
GET /v1/group/user-actions?actionType=CreateMedia&accountId={account-id}&apiKey={api-key}
The result is something like this:
[
{
"actionType": "CreateMedia",
"userId": "be7ea3cd-e313-474e-9e58-8a59589944b0",
"rights": "user_schedule,extended,enterprise",
"resources": [
{
"resourceId": "vNoReUCjxPehywGYUBON3KL8DdegXWxp3O70",
"resourceName": "earth-g94738740d_1920.jpg",
"requestBody": {
"name": "earth-g94738740d_1920.jpg",
"fileExtension": "jpg",
"fileSize": 230895,
"uid": 1665426433655,
"hash": "536c4332d6ff16236a87ad99f3edace4",
"alert": false
}
}
],
"timestamp": "2022-10-10T18:18:20.099Z"
}
]
Request with CSV format
The audit trail reports can be downloaded from the API by using the query params format=csv. They are available in a machine-friendly, CSV format.
CSV report format
Detailed reports contain one data row for each action log - they can be (very) large without a filter.
The CSV file has the following columns.
property | definition | example |
---|---|---|
Timestamp | The date and time of when the action was done. | "2022-10-10T18:07:03.712Z" |
Action Type | Name of the action done in the account. See the If there is no event matching the request, a “204 No Content” code is returned with an empty body.
Action types and resources section for the list. |
"CreateProject" |
User ID | The ID of the user that did the action | “f4376612-1d18-4232-ae8d-fc268e9f54b5” |
The current email of user that did the action. Only present when IncludeUserDetails is set. | "john.doe@acme.com | |
First Name | The current first name of the user that did the action. Only present when IncludeUserDetails is set. | “John” |
Last Name | The current last name of the user that did the action. Only present when includeUserDetails is set. | "Doe" |
Resource Id | Unique ID of the resource | "3UIXojuzE2wL94L4YEwb6pU8AVCReUnV2LCj" |
Resource Name | Name of the resource at the time. | "Countdown WebPage!!!" |
Template Set ID | Unique ID of the Template Set/Style. | "nR1n9fq5k3vhTh6DkQcrt8dth6dRC5sgQpcK" |
Template Set Name | Name of the template at that time. | "WebPage!!!" |
Target | Scheduled target player on tag. | 001d50202b94 |
Serial Number | The service serial number (i.e., main MAC address) of the player. | 001d50220352 |
Conclusion
These examples provide a glimpse into the results obtainable through the Audit Trail API. For a comprehensive overview and detailed instructions, please refer to the attached technical documentation at the top of this page.