Cloud Administration User Event Log APICloud 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 Super Admin activities, see Administration Log Messages for the Cloud Authentication Service.
AuthenticationAuthentication
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 RolesAdministrative 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 KitSoftware Developer Kit
You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.
Request RequirementsRequest 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 ParametersRequest 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 ParametersExample 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 SpecifiedExample 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 MetadataResponse 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 DataResponse 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 |
