Cloud Administration User Event Log API

The Cloud Administration User Event Log API is a REST-based web services interface that allows user event logs to be retrieved from the Cloud Authentication Service. Customers can use this REST API to import the user event logs into their security information and event management (SIEM) solution, such as NetWitness. Event logs are retrieved in chronological order in batches, and do not contain duplicates. Events are retained for 40 days and then purged.

The endpoint, which can be either the SIEM or another client, uses the Administration API Key to call the User Event Log API. The Super Admin generates this key and provides it to the Client Developer, as described in Manage API Keys for the Administration Event Log, User Event Log, and Help Desk APIs.

For information on audit log messages that describe user activities, see User Event Monitor Messages for the Cloud Authentication Service. For Super Admin and Help Desk Admin activities, see Administration Log Messages for the Cloud Authentication Service.

Authentication

Clients calling this API must authenticate themselves by including a JSON Web Token in a request. For instructions on using this token, see Authentication for the Cloud Administration REST APIs.

Administrative Roles

This API can use an API key that is associated with either the Super Administrator or Help Desk Administrator role. For more information, see Manage the Cloud Administration REST API Keys.

Software Developer Kit

You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.

Request Requirements

Use the following information in requests to retrieve user events from the Cloud Authentication Service and deliver them to your SIEM solution.

Method Request URL Response Body Response Body Type Response Codes
GET /AdminInterface/restapi/v1/usereventlog/exportlogs Metadata, plus array of User Event logs application/json 200, 400, 403

Request Parameters

The User Event Log REST API allows the following parameters.

Note: The request query parameter values may contain reserve characters that need to be URL encoded. Otherwise, the server may send a 400 Bad Request error. For example, the ISO 8601 Date and Time format may contain the + character if the specific time zone has an offset from UTC, such as+05:30. The + character needs to be encoded as %2B.

Name Description Type Default Value Example
startTimeAfter Timestamp limit. User events logged after this timestamp are exported. ISO 8601 Date Time Current time - 1 day 2018-05-01T11:22:12.828-05:30
endTimeOnOrBefore Timestamp limit. User events logged before or on this timestamp are exported. ISO 8601 Date Time Current time 2018-05-09T21:06:33.125-05:30
pageNumber Zero-based index of the page to return. Integer 0 5
pageSize Number of records to return in a page (or batch). Value between 1-100. Any value specified outside of this range is treated as 100. Integer 100 50

Example Request with No Parameters

The following example returns log data for the previous 24 hours.

GET /AdminInterface/restapi/v1/usereventlog/exportlogs

Accept: application/json

Authorization: Bearer <JWT token>

Example Request with Start Time Specified

The following example shows an API request with a specified start time.

GET /AdminInterface/restapi/v1/adminlog/exportlogs?startTimeAfter=2018-05-01T11:22:12.828-05:30

Accept: application/json

Authorization: Bearer <JWT token>

Response Metadata

The following table shows the name, description, and type used for API response metadata.

Name Description Type
totalPages Total number of pages (or batches) of results. Integer
totalElements Total number of results. Integer
pageSize Number of results returned in a page (or batch). Integer
currentPage Page number associated with the results returned in the response. Integer

The following sample response metadata displays 684 results with a default page size of 100.

{

"totalPages": 7,

"totalElements": 684,

"pageSize": 100,

"elements": [

{

......

}

]

}

Response Data

The following table shows user event names, types, and descriptions for the API response data.

Name Description Type
eventId ID of user event log. Long
eventLogDate Date and time of user event log, in UTC timezone. Example: 2018-05-13T16:29:59.000 UTC ISO 8601 Date Time
eventType Always set to User. String
eventLevel Event log level, notice, or error. String
eventCategory Authentication or Device Management. String
serverIPAddress IP address of the server where the user event occurs. IP Address in String
tenantId Identifies the customer's deployment. UUID in String
customerName Customer name, as specified in Company Settings. String
userId User identifier. String
sourceIPAddress IP Address of the user who generated user events. IP Address
eventCode User event code. String
eventDescription User event description. String
application Authenticated application. String
method Authentication method. String
deviceName Authentication device name. String
deviceId Authentication device identifier. String
policyId Access policy identifier. String
policyName Access policy name. Boolean
authenticationDetails Authentication details. String
assuranceLevel Assurance level used in the access policy. String