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:

https://{Egnyte Domain}.egnyte.com

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 10,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:

  • relying on the “Retry-After” parameter in the HTTP Response Header that contains the number of seconds after which it is ok to retry the API call, or
  • implementing exponential back-off.
  •  

    Restrictions

    Only admin users (or power users with the "can run reports" role) can retrieve the audit records. If a non-admin user (or a power user without the "can run reports" role) attempts to use this API then an HTTP 403 error will be returned.
    Audit reporting must be available on Egnyte domain’s plan. If the domain’s plan does not support Audit Reporting then an HTTP 403 will be returned.

    Common HTTP Headers

    HTTP Request Headers

    Header Description Possible Value
    Authorization This should use the the OAuth token you obtained through OAuth flow. Bearer {OAuth token}

    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 10,000 events (but may also be empty).
      • A single API request can return up to 10,000 events for at most 1 hour span of event history. In case of a few (or zero) events happening within that (implied) 1 hour span for the cursor, the returned nextCursor will implicitly point to the end of the (1 hr) 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) 1 hour 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

    Retrieve audit events

    GET/pubapi/v2/audit/stream?startDate=startDate
    POST/pubapi/v2/audit/stream

    Parameters:

    Parameter Description Required Possible Values
    startDate Start of date range for the initial set of audit events.
    Format: YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ.
    The start date should be within the last 7 days (from now). To retrieve past audit events outside of the 7 day window, it is needed to use Audit Reporting API v1.
    Yes (it is necessary to specify one of the two parameters: either startDate or nextCursor) Example: 2021-12-08T00:00:00Z
    endDate End of date range for the initial set of audit events.
    Format: YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ.
    No Example: 2021-12-10T00:00:00Z
    nextCursor Iteration pointer for a following (not the initial) request. A cursor is returned in response to the initial request and then every following request generates a new cursor to be used in the next request. Yes (it is necessary to specify one of the two parameters: either startDate or nextCursor) Example: QmlnVGFibGVLZXk=
    auditType Allows to receive only specific types of audit events. If multiple types of events are required, it is recommended to receive all the required types (specifying the list of types in this filter) and then process them on the client as required. Allows filtering audit events by type based on the list of audit event types. No. The default value = ANY, if not specified. ANY or a list of values defined below [FILE_AUDIT, LOGIN_AUDIT, PERMISSION_AUDIT, USER_AUDIT, GROUP_AUDIT, WG_SETTINGS_AUDIT, WORKFLOW_AUDIT, QUALITY_DOCS_AUDIT, QUALITY_DOCS_CATEGORIES_AUDIT, ANY]

    Method-specific Response Codes

    Error Code Error Message HTTP Code Troubleshooting
    Too many requests Your application has exceeded the maximum allowed request rate for this operation. 429 The same request should be retried after some time. One can rely on the “Retry-After” parameter in the HTTP Response Header - the parameter contains the number of seconds after which it is ok to retry the same API call. Alternatively, an exponential back-off should be implemented.
    Bad Request This request is invalid. 400 Please, check if the cursor is older than 7 days. In this case, it is necessary to start again with a specific date range and get a new cursor. It is recommended to use this approach for handling all the Status 400 errors.

    Request Examples

    GET /pubapi/v2/audit/stream

    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 /pubapi/v2/audit/stream

    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"]}'
                

    Sample Request Body

    {
        "startDate": "2021-12-08",
        "endDate": "2021-12-10",
        "auditType": [
            "FILE_AUDIT",
            "LOGIN_AUDIT",
            "PERMISSION_AUDIT"
        ]
    }
    
    or, for following requests (not the initial request)
    {
    	"nextCursor": "QmlnVGFibGVLZXk="
    }
    

    Sample Response Body

    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
    }