Audit Reporting API v2

The Audit Reporting API v2 allows you to programmatically retrieve audit records about login activity, file actions, permission changes, configuration changes etc.. The scope of these actions effectively gives you a 360° view of the activity in your account.

Version 2 and Version 1 difference

Version 2 is a "streaming" version of the Audit API where you can use cursors to keep retrieving subsequent Audit Events. Version 1 requires creating Audit Reports with specific parameters / time range and then retrieve the reports. Documentation for Version 1 of Egnyte Audit Reporting API can be found here.

General

An endpoint for the Audit Reporting API should always begin like this:

This document describes the new near real-time API to fetch audit events for the last 7 days (from now) and to keep retrieving new events. The returned set of events can contain any number of events – from zero up to 5,000 elements. The API response will also contain the “nextCursor” parameter, which should be used to retrieve the next set of API events.

To retrieve past audit events outside of the 7 day window, it is still needed to use Audit Reporting API v1.

Rate Limiting

The new Streaming API endpoint is rate-limited, currently to 10 requests per minute and 100 requests per hour. It is necessary for API clients to handle the 429 “Too Many Requests” HTTP Status and retry requests after some period of time, either:

Restrictions

Common HTTP Headers

HTTP Request Headers

Request flow

1. Requesting the initial set of events, e.g. : /pubapi/v2/audit/stream?startDate=2021-12-08T00:00:00Z
2. Parsing the response:
   • events parameter may contain up to 5,000 events (but may also be empty).
   • A single API request can return up to 5,000 events for at most 30 minutes span of event history. In case of a few (or zero) events happening within that (implied) 30 minutes span for the cursor, the returned nextCursor will implicitly point to the end of the (30 minutes) range, so that the follow-up query will start with the next time span. If 10,000 events have been returned, then the next cursor will implicitly point to the last event in the batch (not to miss any subsequent events).
   • It is perfectly fine for a single request to return no events if none occurred within the (implied) 30 minutes span of history. The API client should get the nextCursor and make the next API request.
   • moreEvents flag indicates whether there are more events to retrieve. If moreEvents parameter is returned as “false”, one can assume that all the events until now have been retrieved and can periodically request more updates.
   • nextCursor should be used for the next request
3. Requesting the next set of events with the "nextCursor" value received on the previous step: /pubapi/v2/audit/stream?nextCursor=..., then going to Step 2
4. If cursor is older than 7 days, the request in Step 3 will cause Error 400 “Bad Request “. In this case, it is necessary to start with Step 1 and get a new cursor (in general, one can use this approach for handling all the Status 400 errors).
5. In case of retrying the same request for handling Status 429 or other (e.g. Status 500) HTTP errors, one can use the same cursor as earlier.

API Methods

GET https://apidemo.egnyte.com/pubapi/v2/audit/stream?startDate=2021-12-08  HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
             

curl -v  -H "Authorization: Bearer 68zc95e3xv954u6k3hbnma3q" https://apidemo.egnyte.com/pubapi/v2/audit/stream?startDate=2021-12-08
            

POST https://apidemo.egnyte.com/pubapi/v2/audit/stream?startDate=2021-12-08  HTTP/1.1
Host: apidemo.egnyte.com
Authorization: Bearer 68zc95e3xv954u6k3hbnma3q
             

curl -X POST 'https://apidemo.egnyte.com/pubapi/v2/audit/stream' \ 
-H 'Content-Type: application/json' \ 
-H 'Authorization: Bearer 68zc95e3xv954u6k3hbnma3q' \ 
--data-raw '{"startDate": "2021-12-08", "auditType": ["FILE_AUDIT", "LOGIN_AUDIT", "PERMISSION_AUDIT"]}'
            

{
    "startDate": "2021-12-08",
    "endDate": "2021-12-10",
    "auditType": [
        "FILE_AUDIT",
        "LOGIN_AUDIT",
        "PERMISSION_AUDIT"
    ]
}

{
	"nextCursor": "QmlnVGFibGVLZXk="
}

Response

{ "nextCursor": "AAN_lwABAX1zZe9AAAAAAAAAAAAAAAAAAAAAAA", 
   "events": 
       [  
           { "date":1638936585716,
             "sourcePath":"/Shared/Departments/Marketing/Branding/Logo.jpg",
             "targetPath":"N/A",
             "user":"Jack Smith ( jsmith@company.com )",
             "userId":"101",
             "action":"Preview",
             "access":"Web UI",
             "ipAddress":"173.226.89.189",
             "actionInfo":"",
             "auditSource":"FILE_AUDIT"
             },
          { "date":1638937051697,
            "sourcePath":"/Shared/Departments/Engineering/ProductY/Photo.png",
            "targetPath":"N/A",
            "user":"Adam Jackson ( ajackson@company.com )",
            "userId":"146",
            "action":"Upload",
            "access":"Web UI",
            "ipAddress":"172.8.18.17",
            "actionInfo":"",
            "auditSource":"FILE_AUDIT"
            },
         { "date":1638940605824,
           "actor":"Jennifer Watkins ( jwatkins@company.com )",
           "subject":"Paul Chen ( pchen@company.com )",
           "action":"Disable",
           "actionInfo":"",
           "source":"Web UI",
           "auditSource":"USER_AUDIT"
           },  
        { "date":1638942414189,
          "actor":"Jennifer Watkins ( jwatkins@company.com )",
          "group":"Engineering",
          "action":"Create",
          "actionInfo":"",
          "source":"Web UI",
          "auditSource":"GROUP_AUDIT"
          } .... 
        ],
    "moreEvents":true
}