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

URL
Description
Method
/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 of full name)
GET
/auditlog/delta
Returns an array of changed auditlog entries since last call (see further down)
GET

Headers

Name
Description
Type
apikey
Your apikey listed in your settings to retrieve the data
string

Filters

Filters can be supplied either as URL parameters or headers.
Name
Description
Type
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 specified 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: https://dc1api.adminbyrequest.com/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”
  • Please 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 represents the time of the last change – not the actual time now
{
  "entries": [],
  "timeNow": 637795099840708375
}

Fields

General
Description
Type
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
endTimeUTC
End time in Coordinated Universal Time (UTC). Will default to endTime if not available
datetime
ssoValidated
If the request was validated by Single Sign-On (SSO) on the endpoint
bit
auditlogLink
Link to this request in the auditlog on www.adminbyrequest.com
string
User
Description
Type
user.account
The user account the end user used to log on to the computer
string
user.fullName
The full name of the 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
user.isAdmin
Determines if the is administrator
bit
Computer
Description
Type
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
Description
Type
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
Description
Type
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
Description
Type
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
Elevated Applications
Description
Type
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
Scan Results
Description
Type
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 of 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,
    "ssoValidated": false,
    "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",
      "isAdmin": false
    },
    "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
      }
    ]
  }
]