Documentation

Public API > Auditlog API.

Documentation Menu

Auditlog API

This page explains how to get your auditlog data extracted. Note that the example array of audit log entries further down shows only the first entry and a subset of scan results for readability. You can use query parameters to filter your search.

Resources

/auditlog Returns an array of auditlog entries GET
/auditlog/{id} Returns one auditlog entry GET
/computers/{computername}/auditlog Returns an array of auditlog entries for a certain computer GET
/users/{user}/auditlog Returns an array of auditlog entries for a certain user (user account or full name) GET
/auditlog/delta Returns an array of changed auditlog entries since last call (see further down) GET
Note that the prefix of urls above depend on which data center you belong to. If USA, use dc2api.adminbyrequest.com. Otherwise (i.e., Europe), use dc1api.adminbyrequest.com.

Headers

apikey Your apikey listed in your settings to retrieve the data string

Filters

Filters can be supplied either as URL parameters or headers.
startid The starting ID you wish to receive. Can be used for incremental offload of data to your own system int
take Maximum number of resources to return. Default is 50 to preserve bandwidth, maximum is 10000. For queries with more than 10000 records, pagination is mandatory int
last Entries are retrieved in ascending order by default. Last returns the latest X number of entries in descending order. Maximum is 10000. int
wantscandetails Use this filter, if you wish to receive detailed lists of scan results. The default is to give you the overall result only bit
type Only return either “Run As Admin” (type=app) or “Admin Sessions” (type=session) entries. string
status Only return entries from Requests – value can be “Pending”, “Approved”, “Denied” or “Quarantined” entries. string
days By default, entries up to 30 days are returned, unless specied otherwise. If startdate is specified, days is not used. int
startdate Only return entries after the specified start date (format: yyyy-mm-dd). date
enddate Only return entries before and including the specified end date (format: yyyy-mm-dd). date
  • Example filtered url to get 10 entries: /auditlog?startid=4050334&take=10&wantscandetails=1
  • Pagination works by using the last id in the list and feeding it as startid in the next query
  • To copy new data to your own system, we recommend to store the highest id (last entry in list) you have retrieved from a previous call and pass this number plus 1 as “startid”
  • Do NOT consistently use a high “take” number or flood the api. We will automatically throttle your account

Delta data

To avoid having to download a full auditlog to find changed auditlog data, you can ask for changed entries (delta). A scenario could be a request is made by a user (new entry). Then it is approved by an administrator (changed entry) and in turn being used by the end user (changed entry again). To get changed entries, follow this procedure:
  • Call /auditlog/delta without parameters one time to get an initial “timeNow”
  • Use this time to get delta data since last call. In the case below, the next call should be /auditlog/delta?deltaTime=637795099840708375
  • Repeat the process of saving “timeNow” to feed to next call as “deltaTime” parameter. In the example below, there were no changes in the interval.
  • Note that timeNow is often the same value from call to call. This is intended, as it is represents the time of the last change – not the actual time now.
{ “entries”: [], “timeNow”: 637795099840708375 }

Fields

id The unique ID of this entry. This ID can be used to query updated information on this entry by appending it to the url to request this resource only int
traceNo The trace number to find this entry in the portal auditlog int
settingsName The name of the matching subsettings or “Global” if no subsetting was matched int
type Type of request (possible values: Run As Admin, Admin Session, Server Session) string
typeCode 0 = Run As Admin, 1 = Admin Session, 2 = Server Session int
status Status of the request (possible values: Open, Running, Finished, Denied, Pending approval, Quarantined) string
statusCode 0 = Open, 1 = Running, 2 = Finished, 3 = Denied, 4 = Pending Approval, 5 = Quarantined, 6 = Expired int
reason Reason supplied by end user string
approvedBy Name of person that approved the request string
deniedReason Reason for denying the request supplied by an administrator string
deniedBy Name of person denying the request string
requestTime Time of a request by end user datetime
requestTimeUTC Request time in Coordinated Universal Time (UTC). Will default to requestTime if not available. datetime
responseTime Time between a request and approval by an administrator timespan
startTime Start time of running the application or starting a session datetime
startTimeUTC Start time in Coordinated Universal Time (UTC). Will default to startTime if not available. datetime
endTime Time when the application or session finished datetime
startTimeUTC End time in Coordinated Universal Time (UTC). Will default to endTime if not available. datetime
auditlogLink Link to this request in the auditlog on www.adminbyrequest.com string
user.account The user account the end user used to log on to the computer string
user.fullName The full name of the user user string
user.email The user’s email address supplied on the request form string
user.phone The user’s phone number supplied on the request form string
computer.name The name of the computer executing the request string
computer.platform Operating system platform (possible values: Windows, Mac, Server) string
computer.platformCode 0 = Windows, 1 = Mac, 2 = Server, int
computer.make The vendor of the machine, as it appears in the inventory string
computer.model The model of the machine, as it appears in the inventory string
application.file The file name of the file executed using Run As Admin string
application.path The file path of the executed application string
application.name The name of the application (description property of file) string
application.vendor The vendor of the application string
application.version The version of the file string
application.sha256 The checksum of the file string
application.scanResult Malware scan result (possible values: Clean, Malicious, Suspicious) string
application.scanResultCode 0 = Clean, 1 = Malicious, 2 = Suspicious int
application.threat Name of malware, if file is malicious or suspicious string
application.virustotalLink Link to the file (checksum) on virustotal.com string
application.preapproved If the file was pre-approved to run bit
installs[].application The name of the application (description property of file) string
installs[].vendor The vendor of the application string
installs[].version The version of the application string
uninstalls[].application The name of the application (description property of file) string
uninstalls[].vendor The vendor of the application string
uninstalls[].version The version of the application string
elevatedApplications[].file The file name of the file executed string
elevatedApplications[].path The file path of the executed application string
elevatedApplications[].name The name of the application (description property of file) string
elevatedApplications[].vendor The vendor of the application string
elevatedApplications[].version The version of the file string
elevatedApplications[].sha256 The checksum of the file string
elevatedApplications[].scanResult Malware scan result (possible values: Clean, Malicious, Suspicious) string
elevatedApplications[].scanResultCode 0 = Clean, 1 = Malicious, 2 = Suspicious int
elevatedApplications[].threat Name of malware, if file is malicious or suspicious string
elevatedApplications[].virustotalLink Link to the file (checksum) on virustotal.com string
scanResults[].scanResult Malware scan result (possible values: Clean, Malicious, Suspicious) string
scanResults[].scanResultCode 0 = Clean, 1 = Malicious, 2 = Suspicious int
scanResults[].engine Name of the antivirus engine with this result string
scanResults[].threat Name of malware, if file is malicious or suspicious string

Example successful request

[ { “id”: 615669, “traceNo”: “34376579”, “settingsName”: “Global”, “type”: “Run As Admin”, “typeCode”: 0, “status”: “Finished”, “statusCode”: 2, “reason”: “Need to update reader. It says out of date when trying to open PDF files from our supplier.”, “approvedBy”: “Jim Kerr”, “deniedReason”: null, “deniedBy”: null, “requestTime”: “2020-04-01T12:03:00”, “requestTimeUTC”: “2020-04-01T12:03:00”, “startTime”: “2020-04-01T12:03:30”, “startTimeUTC”: “2020-04-01T12:03:30”, “endTime”: “2020-04-01T12:09:11”, “endTimeUTC”: “2020-04-01T12:09:11”, “responseTime”: “00:00:05.4100000”, “auditlogLink”: “https://www.adminbyrequest.com/AuditLog?Page=AppElevations&ID=34376579&ShowFilter=false”, “user”: { “account”: “ACME\\PDH”, “fullName”: “Paul David Hewson”, “email”: “pdh@acme.com”, “phone”: “555.345.6789” }, “computer”: { “name”: “W1005623”, “platform”: “Windows”, “platformCode”: 0, “make”: “Dell Inc.”, “model”: “XPS 15 9550” }, “application”: { “file”: “readerdc_uk_fb_crd_install.exe”, “path”: “C:\installers”, “name”: “Adobe Download Manager”, “vendor”: “Adobe Inc.”, “version”: “2.0.0.495s”, “sha256”: “9369FB712545F6B6FEC5FBF8B1DD228E57CA7899933BBE354B7C4351C8700C99”, “scanResult”: “Clean”, “scanResultCode”: 0, “threat”: null, “virustotalLink”: “https://www.virustotal.com/latest-scan/9369FB712545F6B6FEC5FBF8B1DD228E57CA7899933BBE354B7C4351C8700C99”, “preapproved”: false }, “installs”: [ { “application”: “Adobe Acrobat Reader DC”, “version”: “20.006.20042”, “vendor”: “Adobe Systems Incorporated” } ], “uninstalls”: [ { “application”: “Adobe Reader XI (11.0.23)  MUI”, “version”: “11.0.23”, “vendor”: “Adobe Systems Incorporated” } ], “elevatedApplications”: [ { “name”: “Adobe Download Manager”, “path”: “C:\\Users\\pdh\\Downloads”, “file”: “readerdc_uk_fb_crd_install.exe”, “version”: “2.0.0.495s”, “vendor”: “Adobe Inc.”, “sha256”: “9369FB712545F6B6FEC5FBF8B1DD228E57CA7899933BBE354B7C4351C8700C99”, “scanResult”: “Clean”, “scanResultCode”: 0, “threat”: null, “virustotalLink”: “https://www.virustotal.com/latest-scan/9369FB712545F6B6FEC5FBF8B1DD228E57CA7899933BBE354B7C4351C8700C99” }, { “name”: “Adobe Self Extractor”, “path”: “C:\\Users\\pdh\\AppData\\Local\\Adobe\\E1F06F26-140E-4556-A421-788F6C2015BD\\DA1C2141-106A-4BC6-B096-658FCF15DBFC”, “file”: “C12D10CF-96D9-4985-BE1E-00B35267FB0C”, “version”: “20.6.20042.371103”, “vendor”: “Adobe Inc.”, “sha256”: “912525F339CFC46D2CE7402366FC213084D79DEAD70D754F4A73C8BA4AA40650”, “scanResult”: “Clean”, “scanResultCode”: 0, “threat”: null, “virustotalLink”: “https://www.virustotal.com/latest-scan/912525F339CFC46D2CE7402366FC213084D79DEAD70D754F4A73C8BA4AA40650” }, { “name”: “Adobe Acrobat Reader DC”, “path”: “C:\\Program Files (x86)\\Adobe\\Acrobat Reader DC\\Reader”, “file”: “AcroRd32.exe”, “version”: “20.6.20042.371103”, “vendor”: “Adobe Inc.”, “sha256”: “DCD82008D913BFB6FA1ACBC209CB113E24042919FBB8C3E4E9431F194C5B3B47”, “scanResult”: “Clean”, “scanResultCode”: 0, “threat”: null, “virustotalLink”: “https://www.virustotal.com/latest-scan/DCD82008D913BFB6FA1ACBC209CB113E24042919FBB8C3E4E9431F194C5B3B47” } ], “scanResults”: [ { “scanResult”: “Clean”, “scanResultCode”: 0, “engine”: “BitDefender”, “threat”: null }, { “scanResult”: “Clean”, “scanResultCode”: 0, “engine”: “CrowdStrike”, “threat”: null }, { “scanResult”: “Clean”, “scanResultCode”: 0, “engine”: “McAfee”, “threat”: null } ] } ]