Audit Reporting API V1

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, 2019 is represented as “2019-05-27”. Similarly 10:27:01pm on May 27, 2019 is represented as “2019-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": "2019-05-01",
    "date_end": "2019-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": "2019-05-01",
    "date_end": "2019-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	No	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.	No	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.	No	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.	No	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": "2019-05-01",
    "date_end": "2019-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": "2019-08-01",
    "date_end": "2019-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": "2019-08-01",
    "date_end": "2019-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",
    
}

Create Configuration Settings Audit Report

Generates a Configuration Settings Audit Report

POST/pubapi/v1/audit/workgroup-settings

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
users	Array of usernames who performed a change to a configuration settings	No	Array of any Egnyte usernames within your account

Sample Request Body:

{
    "format": "csv",
    "date_start": "2019-08-01",
    "date_end": "2019-08-15",
    "users": [
        "user1",
        "user2"
    ]
}

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, permissions, users, groups or workgroup-settings .

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)

Sample Response Bodies (JSON)

Login Audit Report

{
    "total_count": 100,
    "offset": 10,
    "count": 2,
    "events": [
        {
            "username": "John Smith ( jsmith@company.com )",
             user_id: 121,
            "event": "Failed Attempt",
            "ip_address": "198.51.100.0",
            "access": "Web",
            "time": "2019-05-26T18:35Z"
        },
        {
            "username": "John Smith ( jsmith@company.com )",
             user_id: 121,
            "event": "Login",
            "ip_address": "198.51.100.0",
            "access": "Mobile",
            "time": "2019-05-26T20:06Z"
        }
    ]
}

File Audit Report

{
    "total_count": 100,
    "offset": 10,
    "count": 2,
    "events": [
        {
            "username": "John Smith ( jsmith@company.com )",
             user_id: 121,
            "file": "/Shared/Documents/example.txt",
            "target_path": "/Shared/Documents/subfolder",
            "transaction": "Move File",
            "actionInfo": "N/A",
            "access": "Mobile",
            "time": "2021-02-15T07:58:17Z",
            "ipAddress": "192.168.0.0.1",
            "file_checksum": "acc8b9f0d5d77c5c03cb9961986"
        },
        {
            "username": "Anonymous access Admin (via link)",
            "user_id": 123,
            "folder": "/Shared/Documents/example",
            "link": "https://acme.egnyte.com/h-s/20130526/5b10bafb3c2742b6",
            "transaction": "Download via Link",
            "actionInfo": "N/A",
            "access": "Web",
            "time": "2021-02-15T08:34:37Z"
            "ipAddress": "192.168.0.0.1",
            "file_checksum": "N/A
        }
    ]
}

Permissions Audit Report

{
    "total_count": 100,
    "offset": 10,
    "count": 2,
    "events": [
        {
            "folder": "/Shared/Marketing",
            "assignee": "Sarah Doerr ( sdoerr@company.com )",
            "assignee_id": 107,
            "assigner": "John Doe ( jdoe@company.com )",
            "assigner_id": 101,
            "change": "+Editor",
            "time": "2019-05-26T18:35Z"
        },
        {
            "folder": "/Shared/Engineering",
            "assignee": "Sarah Doerr ( sdoerr@company.com )",
            "assignee_id": 107,
            "assigner": "John Doe ( jdoe@company.com )",
            "assigner_id": 101,
            "change": "Editor>>Owner",
            "time": "2019-05-26T20:06Z"
        }
    ]
}

User Provisioning Audit Report

{
        "total_count": 2,
        "offset": 0,
        "count": 0,
        "events": [
            {
                 "performed_by": "William Black ( wblack@corporate-email.com )",
                 "performed_by_id":102,
                 "subject": "John White ( jwhite@corporate-email.com )",
                 "subject_id":107,
                 "action": "Create",
                 "action_info":"",
                 "date_and_time":"2019-08-03T17:13:58Z",
                 "action_source":"Web UI"
            },{
                 "performed_by": "John White ( jwhite@corporate-email.com )",
                 "performed_by_id":107,
                 "subject": "John White ( jwhite@corporate-email.com )",
                 "subject_id":107,
                 "action": "Password Change",
                 "action_info": "",
                 "date_and_time": "2019-08-03T17:15:57Z",
                 "action_source": "Web UI"
            },
       ]
}

Group Provisioning Audit Report

{
      "total_count”:2,
      "offset":0,
      "count":0,
      "events":[
          {
              "time":"2019-09-14T23:03:22Z",
              ”actor": "John White ( jwhite@corporate-email.com )",
              "actor_id":107,
              "group”:”ProjectManagers”,
              "action":"Create",
              "action_info":"",
              "source":"Web UI"
         },{
              "time":"2019-09-14T23:03:38Z",
              "actor": "John White ( jwhite@corporate-email.com )",
              "actor_id":107,
              "group":"ProjectManagers",
              "action":"Add Users",
              "action_info":"William Black ( wblack@corporate-email.com ),Kate Smith ( ksmith@corporate-email.com )",
              "source":"Web UI"
         }
     ]
}

Configuration Settings Audit Report

{
    "total_count”:2,
    "offset":0,
    "count":0,
    "events":[
        {
            "time":"2021-01-05T23:00:00Z",
            ”actor":"John White ( jwhite@corporate-email.com )"
            "ip_address":"192.168.0.1"
            "setting_screen”:”SECURITY”,
            "setting_name":"security.externalAuthSettings.samlEnabled",
            "old_value":"false",
            "new_value":"true"
         },{
            "time":"2021-01-05T23:00:01Z",
            ”actor":"John White ( jwhite@corporate-email.com )"
            "ip_address":"192.168.0.1"
            "setting_screen”:”SECURITY”,
            "setting_name":"security.externalAuthSettings.samlSettings.idpName",
            "old_value":"onelogin",
            "new_value":"Duo"
         }
     ]
}

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 audit report types : logins, files, permissions, users, groups, workgroup-settings.

Response

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

version 72 as of 3 years ago by Vitaly Obernikhin

Audit Reporting API V1

Formats

Dates and Times

Audit Report Data

Retrieving Audit Reports

Restrictions

Common HTTP Headers

HTTP Request Headers

HTTP Response Headers

Common Response Codes

Error Messages

API Methods

Create Login Audit Report

Parameters:

Sample Request Body

Method-specific Response Header

Sample Response Body

Create File Audit Report

Parameters:

Sample Request Body

Method-specific Response Header

Sample Response Body

Create Permissions Audit Report

Parameters:

Sample Request Body:

Method-specific Response Header

Sample Response Body:

Create User Provisioning Audit Report

Parameters:

Sample Request Body:

Method-specific Response Header

Sample Response Body:

Create Group Provisioning Audit Report

Parameters:

Sample Request Body:

Method-specific Response Header

Sample Response Body:

Create Configuration Settings Audit Report

Parameters:

Sample Request Body:

Method-specific Response Header

Sample Response Body:

Check Audit Report Generation Status

Method-specific Response Header

Sample Response Body

Method-specific Response Codes:

Retrieve Audit Report

Method-specific Response Header:

Sample Response Body (csv)

Sample Response Bodies (JSON)

Login Audit Report

File Audit Report

Permissions Audit Report

User Provisioning Audit Report

Group Provisioning Audit Report

Configuration Settings Audit Report

Method-specific Response Codes:

Delete Audit report

Response

Docs Navigation