on Sep 14, 2018The 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 RSA 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 the Cloud Administration API Keys.
For information on audit log messages that describe Super 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 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 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.
| 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 |