Skip to content

Audit API

This endpoint allows to retrieve audit information from Workspace ONE Access. This information is typically used to generate information about login activity with Workspace ONE Access, along with retrieving various audit information about SaaS Workspace ONE Access instance.

HTTP Request

GET https://[tenant location]/analytics/reports/audit/

Input parameters

Parameter Required Description
tenant location Yes (URL) Hostname of your tenant
fromMillis No (URL) Filter events no older than this time, milliseconds since epoch, defaults to 3 days ago (now-96 hours)
toMillis No (URL) filter events no newer than this time, milliseconds since epoch, defaults to now.
pageSize No (URL) Max page size of the results, max allowed value is 5000, which is default
startIndex No (URL) Use offset to page through the results
objectType No (URL) Filter specific types of audit events or affected objects. For details, please see the table below
action No (URL) Filter event types even further by specifying what action was taken when the event was generated

Note

To convert time to epoch milliseconds you can use various wed tools. For example, https://www.epochconverter.com/

To query Audit API via shell

In this example I am retrieving all audit events of type LOGIN and I am restricting the time with toMillis parameter.

curl -H 'authorization: Bearer <your token here>' \
<your tenant name here>/analytics/reports/audit?/analytics/reports/audit?fromMillis=1559499975000\&objectType=LOGIN| json_pp

Workspace ONE Access will return the following as a response:

In this example we see 2 events of LOGIN type for the username admin the auth method used is password against local directory.

{
   "header" : [
      "reports.dateAndTime",
      "reports.userDomain",
      "reports.Event",
      "reports.object",
      ""
   ],
   "data" : [
      [
         "1561399981109",
         "admin (System Domain)",
         "LOGIN (Password (Local Directory))",
         null,
         "{\"baseType\":\"Action\",\"uuid\":\"fe0944c3-5e69-425c-92ee-9db0b099d1aa\",\"timestamp\":1561399981109,\"organizationId\":252221,\"tenantId\":\"<your tenant id>\",\"actorId\":5723506,\"actorUserName\":\"admin\",\"actorDomain\":\"System Domain\",\"actorUuid\":\"35ac32d1-1565-4ab4-ad1a-191120540590\",\"clientId\":null,\"deviceId\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.169 Safari/537.36\",\"workspaceId\":null,\"sourceIp\":\"208.91.2.2\",\"objectType\":\"LOGIN\",\"objectId\":null,\"objectName\":null,\"values\":{\"deviceType\":\"browser\",\"success\":\"true\",\"authMethods\":\"Password (Local Directory)\",\"actorExternalId\":null}}"
      ],
      [
         "1561357380574",
         "admin (System Domain)",
         "LOGIN (Password (Local Directory))",
         null,
         "{\"baseType\":\"Action\",\"uuid\":\"314ee065-744f-4188-b595-0aa961ff00b7\",\"timestamp\":1561357380574,\"organizationId\":252221,\"tenantId\":\"<your tenant id>\",\"actorId\":5723506,\"actorUserName\":\"admin\",\"actorDomain\":\"System Domain\",\"actorUuid\":\"35ac32d1-1565-4ab4-ad1a-191120540590\",\"clientId\":null,\"deviceId\":\"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.169 Safari/537.36\",\"workspaceId\":null,\"sourceIp\":\"66.170.99.1\",\"objectType\":\"LOGIN\",\"objectId\":null,\"objectName\":null,\"values\":{\"deviceType\":\"browser\",\"success\":\"true\",\"authMethods\":\"Password (Local Directory)\",\"actorExternalId\":null}}"
      ]
   ],
   "_links" : {
      "self" : {
         "href" : "/analytics/reports/audit?fromMillis=1561142523041&toMillis=1561401723041&objectType=LOGIN&pageSize=5000&startIndex=0"
      }
   },
   "headerArg" : [
      "",
      "",
      "",
      "",
      ""
   ]
}

Types and actions for audit events

There are various types of audit events that can be retrieved. The table below provides a list of most common event types.

Type Description Action
LOGIN Allows to see information about who logged in when and what auth method was used as well as details about IP address, user agent string, etc. failureMessage - the reason if the login attempt failed. authMethods - the authentication methods used. No
Group Allows to see information about group activity in IDM Yes
LAUNCH Allows to see information about who launched what applications and when. Values: success - if the launch attempt was successful. failureMessage - the reason if the launch attempt failed. resourceType - the type of application launched. No
LOGIN_ERROR Allows to see information about any launch failures. Use this action type only if the login did not fail because of wrong user input. It could be a failure because of configuration or system errors. No
DyrectorySyncProfile Allows to see information about directory sync No
AppEntitlement Allows to see information about what applications are entitled to what groups and users Yes
LAUNCH_ERROR User launched an application with an invalid request or if we could not get resource name, UUID or type. Values: failureMessage - the reason if the launch attempt failed.

Important

Types are case sensitive!

For the actions, there are several types of action filters available:

Action Description
Create Object was created
Update Object was updated
Delete Object was deleted
Link object was linked
Unlink Object was unlinked

Output parameters

Depending on the objectType retrieved and the action filter specified, API can return various parameters. The table below provides the information about the most used parameters.

Output parameter Description
actorId The userID of the user who performed the event. In the case of a system event, this the value of this attribute will be null. ActorIds are presented in integer format in the case of a user. In the case of a system service, the return will be null.
actorUserName The username of the user who performed the event. In the case of a system event, the value of this attribute will be null. Expected values include both usernames of user accounts in vIDM, as well as system services. Ex: jdoe.
actorDomain The domain of the user who performed the event. In the case of a system event, the value of this attribute will be null. In the case of a user generated event, the domain of the user will be returned. Ex: vmware.com
actorUUid The UUID of the user who performed the event. Return values will always be in standard UUID format. Ex:8c2a83a2-a546-4571-b16c-ed11a8f51725
objectType ObjectType describes the category of event that was recorded. There are many object types that span both end user activities such as authentication or application launch, and admin activities like entitlements. Please, see the table above the describes various object types.
objectId ObjectID represents the unique internal identifier of the object being modified or interacted with. Depending on the object name and type, different ID formats may be returned.
objectName ObjectName describes the object being modified or interacted with. This can take the form of a specific user, application, configuration, or tenant.
objectAction ObjectAction defines which action was taken against the object in an Audit baseType event. As an example, when updating a user or user entitlements, you would find the objectAction "UPDATE". However, in the case of baseType=Action, this attribute will not appear as the action is defined in objectType.
baseType BaseType represents the type of record being returned. There are two possibilities, Audit and Action. Audit events indicate changes to the database as a result of the event. Action events are not directly related to database changes.
timeStamp Time stamp for event in milliseconds UTC since Jan 1, 1970.
uuid Uuid for the specific audit record. This identifier is unique for each record, including multiple instances of the same type of event. Output value is standard UUID format. This value is not particularly useful except when searching for a specific, already known event record. Example UUID: 07b6c947-f025-422f-be2c-3c87b0f3c017
organizationId Unique numerical identifier for the VMware Identity Manager tenant.
tenantId This attribute is the customers tenant identifier. The value should match the prefix of the environment URL in the following format {tenantId}.vmwareidentity.com.
sourceIP This attribute outputs the sourceIP for the machine which issued the request. Values can take on either the IPv4 format. Example IPv4: 168.175.34.12
authMethods This attribute can return one or more authentication methods used for the request. The authentication methods returned correspond directly with the auth adapter labels in the VMware Identity Manager admin console. Multiple auth methods will be listed in comma delimited format. Example: "method1", "method2".

The available Auth Methods that can be returned as part of Audit API response are listed below:

  • Password (AirWatch Connector)
  • Device Compliance (with AirWatch)
  • VMware Verify
  • Mobile SSO (for iOS)
  • Password (Local Directory)
  • Mobile SSO (for Android)
  • Certificate (Cloud Deployment)
  • vIDM Password - Displayed when user authenticates with an external directory using the vIDM connector