Cloud Administration Retrieve Authentication Audit Logs API

The Cloud Administration Retrieve Authentication Audit Logs API enables Help Desk administrators to retrieve authentication audit logs for a specific user for the 100 most recent events sorted in descending order by event time. The API filters by event code and specified date range. Pagination is not supported.

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 to retrieve authentication audit logs for a specific user. The <userId> parameter is a unique user identifier that is sent in the response to the SecurID User Details API.

Method Request URL Response Content Type Response Codes
GET /AdminInterface/restapi/v1/users/
<userId>/authlogs/		 application/json 200, 400, 403, 404, 500

Resource Identifiers

The following table describes resource identifiers for the Retrieve Authentication Audit Logs API.

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.

Property Description Type
<userId> Identifies the user. String
eventCode

(Optional) User event code. Limits results to events with the specified eventCode value.

For more information, see User Event Monitor Messages for the Cloud Authentication Service.

 Integer
startTimeAfter (Optional) Limits results to events that occurred after the specified date. Must be before endTimeOnOrBefore if that is also specified.

ISO 8601 Date Time

See https://www.w3.org/TR/NOTE-datetime for information on ISO 8601 format.
endTimeOnOrBefore (Optional) Limits results to events that occurred before or on the specified date. Must be after startTimeAfter if that is also specified.

ISO 8601 Date Time

See https://www.w3.org/TR/NOTE-datetime for information on ISO 8601 format..

Example Request Data

The following example displays a request.

GET http://localhost:8886/AdminInterface/restapi/v1/users/a780e57f-98e7-4303-9ce4-34afed539928/authlogs?

startTimeAfter=2018-11-08T22:44:00.000Z&endTimeOnOrBefore=2018-11-10T22:44:00.000Z&eventCode=902

Authorization: Bearer <JWT token>

Example Response Data

The following example displays a response when the request succeeds.

[

{

"eventId": "9a6772f1-d80c-4b6f-8841-c0f32521a534",

"eventLogDate": "2018-11-09T15:54:44.000Z",

"eventType": "user",

"eventLevel": "error",

"eventCategory": "Authentication",

"customerName": "mycompanyname",

"user": "mabbott",

"sourceIPAddress": "191.237.22.167",

"eventCode": "902",

"eventDescription": "Portal logon failed - Authentication failed.",

"application": "Portal",

"method": "password",

"deviceName": "null",

"authenticationDetails": null,

"assuranceLevel": null

}

]

Response Property Descriptions

The following table shows API response data.

Property Description Type
eventId The user event log. String
eventLogDate

Date/time of user event log, in Universal Time Coordinated (UTC) time. Example: 2018-05-13T16:29:59.000Z

See https://www.w3.org/TR/NOTE-datetime for information on ISO 8601 format.

 ISO 8601 Date Time
eventType Set to user. String
eventLevel

Event log level values are:

  • Notice: Activity is successfully completed.
  • Error: Activity completed with an error.
 String
eventCategory Authentication or Device Management. String
customerName Specified in the Cloud Administration Console on the Company Settings page. String
user User identifier. String
sourceIPAddress IP address of the user who generated the event. IP Address
eventCode User event code.

For more information, see User Event Monitor Messages for the Cloud Authentication Service.

 Integer
eventDescription User event description. String
application Application authenticated. String
method Authentication method. Integer
deviceName Authentication device name. String
authenticationDetails Authentication details. String
assuranceLevel Authentication assurance level. String

Response Codes

The API returns the following response codes.

Code Description
200 Authentication logs are successfully found.
400

Operation is not performed. One of the following messages is returned:

  • StartDateTime equals or exceeds EndDateTime.
  • Date format not in ISO format.
  • Unrecognized parameter is passed.
403 Not authorized to perform the request.
404 User ID is not found.
500 Internal error occurred when processing the request.
429 Too many requests.