Audit Reporting API

The Audit Reporting API allows you to programmatically generate and retrieve reports on login activity, file actions, and permission changes. The scope of these reports effectively gives you a 360° view of the activity in your account.

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

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

Specific endpoints are listed with each method.

Formats

Dates and Times

Dates and times are in ISO 8601 format. For example, May 27, 2012 is represented as “2012-05-27”. Similarly 10:27:01pm on May 27, 2012 is represented as “2012-05-27T22:27:01Z”.

Audit Report Data

Audit report data can be returned in either Comma Separated Value (.CSV) or JSON format. The desired format is specified when submitting a report generation request. The .CSV formatted response is identical to the corresponding .CSV file downloaded via the Egnyte audit report UI.

Retrieving Audit Reports

Audit reports are generated asynchronously. After submitting a POST to trigger report generation, a reference to a job resource is returned. This job resource should be periodically polled (but no more frequently than once every 2 minutes) to track the generation status. The job resource will return HTTP code 200 with status message indicating “running” while the report is being generated. Once the report is ready, the job resource will return a 303 HTTP code with a reference to the URI for the completed report.

Restrictions

Only admin users (or power users with the "can run reports" role) can generate the reports. If a non-admin user (or a power user without the "can run reports" role) attempts to call 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
Content-Type Specifies the format of request body application/json
Authorization This should use the the OAuth token you obtained through OAuth flow. Bearer {OAuth token}

HTTP Response Headers

Header Description Possible Value
Content-Type Specifies the format of response body application/json

Common Response Codes

Code Description
202 Successful operation—audit report generation initiated
400 Request is syntactically incorrect
401 Authorization failure
404 Report or job not found

Error Messages

Errors are returned in the HTTP Status Code of the response. Human readable error messages are returned in an “Errors” JSON object in the response body. An example is shown below.

HTTP/1.1 404 NOT FOUND
{
    "Errors": [
        {
            "description": "Audit report does not exist.",
            "code": "404"
        }
    ]
}

API Methods

Create Login Audit Report

POST /pubapi/v1/audit/logins

Parameters:

Parameter Description Required Possible Values
format Determines format of audit report data. Yes csv (Comma Separated Value) or json (JSON format)
date_start Start of date range for report. Yes Any past date in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format.  
date_end End of date range for report. Yes Any date after the date_start value in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format
events List of events to report on. At least one event must be specified. Yes logins, logouts, account_lockouts, password_resets, failed_attempts
access_points List of Egnyte access points covered by report. If not specified or empty then report will cover all access points. No Web, FTP, Mobile
users List of usernames to report on. If not specified or empty then report will cover all users. No Any Egnyte usernames within your account.
suppress_emails Boolean value that indicates whether emails on report completion should be suppressed. When true, users won't receive emails. No true, false (default)

Sample Request Body

{
    "format": "json",
    "date_start": "2012-05-01",
    "date_end": "2012-05-20",
    "access_points": [
        "web",
        "ftp"
    ],
    "users": [
        "jsmith",
        "kjohnson"
    ],
    "events": [
        "logins",
        "failed_attempts"
    ]
}

Method-specific Response Header

Header Description Possible Value
Location Specifies the URL location for an audit report, including the report ID. https://{domain}.egnyte.com/pubapi/v1/audit/jobs/{id}

Sample Response Body

{
    "id": "12345678",
    
}

Create File Audit Report

POST /pubapi/v1/audit/files

Parameters:

Parameter Description Required Possible Values
format Determines format of audit report data. Yes csv (Comma Separated Value) or json (JSON format)
date_start Start of date range for report. Yes Any past date in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format.  Note that timestamp formats in this call will not be rejected; however, the time portion is ignored.
date_end End of date range for report. Yes Any date after the date_start value in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format
folders List of one or more absolute folder paths. At least one path must be specified, unless a value for the file parameter is specified instead. Yes (unless a value for the file parameter is specified instead) Absolute folder path for the destination folder(s)
file Name of a specific file to report on. Supports use of ‘*’ wildcard (cannot start with ‘*’ however). No Absolute folder path for the destination file
users List of usernames to report on. If not specified or empty then report will cover all users. No Any Egnyte usernames within your account.
transaction_type List of one or more transactions to report on. If empty, then report will cover all access points. No upload, download, preview, delete, copy, move, create_folder, restore_trash, delete_trash, create_link, delete_link, download_link
suppress_emails Boolean value that indicates whether emails on report completion should be suppressed. When true, users won't receive emails. No true, false (default)

Sample Request Body

{
    "format": "json",
    "date_start": "2012-05-01",
    "date_end": "2012-05-20",
    "transaction_type": [
        "download",
        "preview"
    ],
    "users": [
        "jsmith",
        "kjohnson"
    ],
    "folders": [
        "/Shared/Marketing",
        "/Shared/Engineering"
    ]
}

Method-specific Response Header

Header Description Possible Value
Location Specifies the URL location for an audit report, including the report ID. https://{domain}.egnyte.com/pubapi/v1/audit/jobs/{id}

Sample Response Body

{
    "id": "12345678",
    
}

Create Permissions Audit Report

Generates a Permissions Audit Report

POST /pubapi/v1/audit/permissions

Parameters:

Parameter Description Required Possible Values
format Determines format of audit report data. Yes csv (Comma Separated Value) or json (JSON format)
date_start Start of date range for report. Yes Any past date in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format.  Note that timestamp formats in this call will not be rejected; however, the time portion is ignored.
date_end End of date range for report. Yes Any date after the date_start value in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format
folders List of one or more absolute folder paths. If not specified or empty then report will cover all folders Yes Absolute folder path for the destination folder(s)
assigners List of users who have assigned permissions. If not specified or empty then report will cover all users. Yes Any Egnyte usernames within your account.
assignee_users List of users who have been granted permissions. If not specified or empty then report will not cover any users, just groups. Yes Any Egnyte usernames within your account.
assignee_groups List of groups that have been granted permissions. If not specified or empty, then report will not cover any users, just groups. Yes Any Egnyte group names within your account.
suppress_emails Boolean value that indicates whether emails on report completion should be suppressed. When true, users won't receive emails. No true, false (default)

Sample Request Body:

{
    "format": "json",
    "date_start": "2012-05-01",
    "date_end": "2012-05-20",
    "assigners": [
        "jsmith",
        "kjohnson"
    ],
    "assignee_users": [
        "rbrown",
        "mjones"
    ],
    "folders": [
        "/Shared/Marketing",
        "/Shared/Engineering"
    ]
}

Method-specific Response Header

Header Description Possible Value
Location Specifies the URL location for an audit report, including the report ID. https://{domain}.egnyte.com/pubapi/v1/audit/jobs/{id}

Sample Response Body:

{
    "id": "12345678",
    
}

Create User Provisioning Audit Report

Generates a User Provisioning Audit Report

POST /pubapi/v1/audit/users

Parameters:

Parameter Description Required Possible Values
format Determines format of audit report data. Yes csv (Comma Separated Value) or json (JSON format)
date_start Start of date range for report. Yes Any past date in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format.  Note that timestamp formats in this call will not be rejected; however, the time portion is ignored.
date_end End of date range for report. Yes Any date after the date_start value in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format
action_type The actions to report on No Array of actions to report on: CREATE, UPDATE, DISABLE, ENABLE, DELETE, PASSWORD_RESET, PASSWORD_CHANGE
performed_by Array of usernames who performed a change to a user No Array of any Egnyte usernames within your account
include_system_actions Whether or not the report should include system actions. No true, false
subject Array of users to report on. No Array of any Egnyte usernames within your account.

Sample Request Body:

{
    "format": "json",
    "date_start": "2018-08-01",
    "date_end": "2018-08-15",
    "action_type":["CREATE", "PASSWORD_RESET", "PASSWORD_CHANGE"],
    "subject":["standarduser1@mydomain","standarduser2@mydomain"]
}

Method-specific Response Header

Header Description Possible Value
Location Specifies the URL location for an audit report, including the report ID. https://{domain}.egnyte.com/pubapi/v1/audit/jobs/{id}

Sample Response Body:

{
    "id": "12345678",
    
}

Create Group Provisioning Audit Report

Generates a Group Provisioning Audit Report

POST/pubapi/v1/audit/groups

Parameters:

Parameter Description Required Possible Values
format Determines format of audit report data. Yes csv (Comma Separated Value) or json (JSON format)
date_start Start of date range for report. Yes Any past date in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format.  Note that timestamp formats in this call will not be rejected; however, the time portion is ignored.
date_end End of date range for report. Yes Any date after the date_start value in YYYY-MM-DD or ISO 8601 YYYY-MM-DD'T'HH:MM:SSZ format
action_type The actions to report on No Array of actions to report on: CREATE, ADD_USERS, REMOVE_USERS, RENAME, DELETE.
users Array of usernames who performed a change to a group No Array of any Egnyte usernames within your account
include_system_actions Whether or not the report should include system actions. No true, false
groups Array of groups to report on. No Array of groups (case-insensitive).

Sample Request Body:

{
    "format": "csv",
    "date_start": "2018-08-01",
    "date_end": "2018-08-15",
    "action_type":["CREATE", "ADD_USERS"],
    "users":["standarduser1@mydomain","standarduser2@mydomain"],
    "groups":["ProjectManagers","Electricians"],
    "include_system_actions":true
}

Method-specific Response Header

Header Description Possible Value
Location Specifies the URL location for an audit report, including the report ID. https://{domain}.egnyte.com/pubapi/v1/audit/jobs/{id}

Sample Response Body:

{
    "id": "12345678",
    
}

Check Audit Report Generation Status

Checks status of a requested audit report generation.

GET /pubapi/v1/audit/jobs/{id}

Method-specific Response Header

Header Description Possible Value
Location Specifies the URL location for an audit report, including the report ID ((included once report generation is complete). https://domain.egnyte.com/pubapi/v1/audit/{type}/{id}

Sample Response Body

{
    "status": "running"
}

OR

{
    "status": "completed"
}

Method-specific Response Codes:

Error Description
200 Report generation ongoing
303 Report generation complete

Retrieve Audit Report

Checks status of a requested audit report generation.

GET /pubapi/v1/audit/{type}/{id}

Input one of the following types into the endpoint above: logins, files, or permissions.

The following optional query string parameters are supported when requested response type for report data is JSON.

Parameter Description Required Possible Values
offset Start at this event (0 = first event). If not specified, defaults to 0. No Any non-negative integer.
count Send this number of events. If not specified, all events will be sent. No Any non-negative integer.

Method-specific Response Header:

Header Description Possible Value
Content-Type Specifies the format of response body application/json
OR
text/csv

Sample Response Body (csv)

CSV file data (text)

OR

Sample Response Bodies (JSON)

Login Audit Report
{
    "total_count": 100,
    "offset": 10,
    "count": 2,
    "events": [
        {
            "username": "jsmith",
            "event": "Failed Attempt",
            "ip_address": "198.51.100.0",
            "access": "Web",
            "time": "2013-05-26T18:35Z"
        },
        {
            "username": "jsmith",
            "event": "Login",
            "ip_address": "198.51.100.0",
            "access": "Mobile",
            "time": "2013-05-26T20:06Z"
        }
    ]
}
File Audit Report
{
    "total_count": 100,
    "offset": 10,
    "count": 2,
    "events": [
        {
            "username": "jsmith",
            "file": "/Shared/Documents/example.txt",
            "target_path": "/Shared/Documents/subfolder",
            "transaction": "Move File",
            "access": "Mobile",
            "time": "2013-05-26T18:35Z"
        },
        {
            "location": "Sunnyvale, California, US(198.51.100.0)",
            "folder": "/Shared/Documents/example",
            "link": "https://acme.egnyte.com/h-s/20130526/5b10bafb3c2742b6",
            "transaction": "DownloadLink",
            "access": "Web",
            "time": "2013-05-26T20: 06Z"
        }
    ]
}
Permissions Audit Report
{
    "total_count": 100,
    "offset": 10,
    "count": 2,
    "events": [
        {
            "folder": "/Shared/Marketing",
            "assignee": "jsmith",
            "assigner": "mjones",
            "change": "+Editor",
            "time": "2013-05-26T18:35Z"
        },
        {
            "folder": "/Shared/Engineering",
            "assignee": "mjones",
            "assigner": "jsmith",
            "change": "Editor>>Owner",
            "time": "2013-05-26T20:06Z"
        }
    ]
}
User Provisioning Audit Report
{
        "total_count": 2,
        "offset": 0,
        "count": 0,
        "events": [
            {
                 "performed_by": "William Black ( wblack@corporate-email.com )",
                 "subject": "John White ( jwhite@corporate-email.com )",
                 "action": "Create",
                 "action_info":"",
                 "date_and_time":"2018-08-03T17:13:58Z",
                 "action_source":"Web UI"
            },{
                 "performed_by": "John White ( jwhite@corporate-email.com )",
                 "subject": "John White ( jwhite@corporate-email.com )",
                 "action": "Password Change",
                 "action_info": "",
                 "date_and_time": "2018-08-03T17:15:57Z",
                 "action_source": "Web UI"
            },
       ]
}
Group Provisioning Audit Report
{
      "total_count”:2,
      "offset":0,
      "count":0,
      "events":[
          {
              "time":"2018-09-14T23:03:22Z",
              ”actor": "John White ( jwhite@corporate-email.com )",
              "group”:”ProjectManagers”,
              "action":"Create",
              "action_info":"",
              "source":"Web UI"
         },{
              "time":"2018-09-14T23:03:38Z",
              "actor": "John White ( jwhite@corporate-email.com )",
              "group":"ProjectManagers",
              "action":"Add Users",
              "action_info":"William Black ( wblack@corporate-email.com ),Kate Smith ( ksmith@corporate-email.com )",
              "source":"Web UI"
         }
     ]
}

Method-specific Response Codes:

Error Description
200 Successful operation—report data returned

Delete Audit report

Deletes an existing audit report.

DELETE /pubapi/v1/audit/{type}/{id}

{type} should be one of the following : logins, files, or permissions.

Response

On success, this request returns a 204 status code with no response body.