# Audit Trail

These are a collection of endpoints that allow you to interact with the Audit Trail. These are audit logs that are generated whenever an action is performed on your Console.

# Fetch Audit Trail Logs

GET /api/v1/audit_trail/fetch

Returns a list of audit trail logs.

Required Parameters

auth_token string
A valid auth token

Optional Parameters

tz string
Timezone for standardised timestamps (fields that end in "_std"). Use the pytz names to specify the timezone
limit int
Defaults to: 100
Number of audit logs returned in each page of results. Cannot be used with a cursor.
cursor string
The cursor string retrieved from the cursor element returned along with a page while doing pagination.
action_filter string
Only return logs from this action type (example values are user_login, device_push_settings, user_assign_to_flock, flock_move)
search_term string
Only return logs that have a field matching this query term. '%20' should be used in place of any spaces between words.
start_date string
Only return logs that were created after the given date. This should be in the format "yyyy-mm-dd".
end_date string
Only return logs that were created before the given date. This should be in the format "yyyy-mm-dd".

Response

JSON structure with list of logs and the previous and next cursor.

Example

    Response
    {
      "audit_trail": [
        {
          "action_type": "user_login",
          "additional_information": null,
          "flock_id": null,
          "id": 73,
          "message": "User <user_email> logged in",
          "timestamp": "2020-04-03 12:56:42 UTC+0000",
          "user": "<user_email>",
          "user_browser_agent": "<browser_agent_string>",
          "user_browser_language": "en-US,en;q=0.9",
          "user_ip": "<user_ip>"
        },
        {
          "action_type": "user_login",
          "additional_information": null,
          "flock_id": null,
          "id": 72,
          "message": "User <user_email> logged in",
          "timestamp": "2020-04-03 09:53:59 UTC+0000",
          "user": "<user_email>",
          "user_browser_agent": "<browser_agent_string>",
          "user_browser_language": "en-US,en;q=0.9",
          "user_ip": "<user_ip>"
        },
        {
          "action_type": "user_login",
          "additional_information": null,
          "flock_id": null,
          "id": 71,
          "message": "User <user_email> logged in",
          "timestamp": "2020-04-02 13:40:05 UTC+0000",
          "user": "<user_email>",
          "user_browser_agent": "<browser_agent_string>",
          "user_browser_language": "en-US,en;q=0.9",
          "user_ip": "<user_ip>"
        },
        {
          "action_type": "device_schedule_reboot",
          "additional_information": null,
          "flock_id": "flock:default",
          "id": 70,
          "message": "User 'API Token' scheduled the device <device_id> to be rebooted",
          "timestamp": "2020-04-02 13:14:49 UTC+0000",
          "user": "<user_email>",
          "user_browser_agent": "<browser_agent_string>",
          "user_browser_language": "",
          "user_ip": "<user_ip>"
        },
        {
          "action_type": "device_schedule_reboot",
          "additional_information": null,
          "flock_id": "flock:default",
          "id": 69,
          "message": "User 'API Token' scheduled the device <device_id> to be rebooted",
          "timestamp": "2020-04-02 13:11:27 UTC+0000",
          "user": "<user_email>",
          "user_browser_agent": "<browser_agent_string>",
          "user_browser_language": "",
          "user_ip": "<user_ip>"
        }
      ],
      "cursor": {
        "next": "MDo2OTo1OjM6MjoxNQ==",
        "prev": null
      },
      "page_count": 15,
      "page_number": 1,
      "result": "success"
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71

    # Purge Audit Trail Logs

    DANGER

    Purging logs will permanently remove them and they will not be recoverable.

    POST /api/v1/audit_trail/purge

    Deletes audit_trail logs older than (and including) a provided id.

    Required Parameters

    auth_token string
    A valid auth token
    id int
    Delete logs before this point (including this point)

    Response

    A JSON message with a result indicator and message.

    Example

      Response
      {
        "msg": "72 logs purged successfully",
        "result": "success"
      }
      
      1
      2
      3
      4

      # Download Audit Trail Logs

      GET /api/v1/audit_trail/download/json

      Downloads a zipped json file of audit trail entries.

      Required Parameters

      auth_token string
      A valid auth token

      Response

      A `canary_audit_trail.json.zip` file of type `application/x-zip-compressed`.

      Example

        The output of this response would be a downloaded file.