Audit Trail API

Release date: April 16^th, 2022

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.

To use this API, you will need to generate an API Key from your ARYA account,please see this page on how to generate API Keys in SpinetiX ARYA™.

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”
Email	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.