Cloud Administration Anomalous Users API

Use this REST API to retrieve a list of users who exhibit anomalous behavior. The API retrieves information for each user as described in Response Data. Events are retrieved according to severity, in descending order, and do not contain duplicates. You can filter events by date range. Up to 500 unique anomalous events can be retrieved at any given time.

For more information on identity confidence and anomalous user events, see Identity Confidence.

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 logs for anomalous user events.

Method Request URL Response Body Response Body Type Response Codes
GET /AdminInterface/restapi/v1/riskdashboard/anomaloususerevents User authenticator details with property application/json 200, 400, 403

Request Parameters

Both request parameters are optional.

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. ISO 8601 Date Time Current time - 1 day 2021-01-13T11:22:12.828-04:30
endTimeOnOrBefore Timestamp limit. ISO 8601 Date Time Current time 2021-01-14T11:22:12.828-04:30

The following table describes how these parameters are used.

Parameter Provided Result
Only startTimeAfter

endTimeOnOrBefore = startTimeAfter + 24 hours
Only endTimeOnOrBefore startTimeAfter = endTimeOnOrBefore - 24 hours
Both Data is returned for the specified date range. The date range cannot exceed 30 days.
Neither

endTimeOnOrBefore = current Day:Time

startTimeAfter = endTimeOnOrBefore - 24 hours

Example Request with No Parameters

This example returns log data for the past 24 hours.

GET

/AdminInterface/restapi/v1/riskdashboard/anomaloususerevents

Accept: application/json

Authorization: Bearer <JWT token>

Example Request with Start Time Specified

This example returns log data for a specified start time.

GET /AdminInterface/restapi/v1/riskdashboard/anomaloususerevents?startTimeAfter=2021-01-13T11:22:12.828-04:30

Accept: application/json

Authorization: Bearer <JWT token>

Response Metadata

Name Description Type
status

The Cloud Authentication Service sends the following status codes when processing input parameters:

  • Status 0 - Successful processing.

  • Status 1 - One of the following errors was found:

    • INVALID_START_TIME indicates the startTimeAfter is greater than the current day:time.

    • INVALID_END_TIME indicates the endTimeOnOrBefore is greater than the current day:time.

    • INVALID_DATETIME_RANGE indicates the startTimeAfter is greater than endTimeOnOrBefore.

    • EXCEEDED_PERMISSIBLE_DATE_RANGE indicates the endTimeOnOrBefore minus startTimeAfter is greater than 30 days.

 int
listOfConfidenceEventsExportEntries List of anomalous user events found during authentication. Boolean flag is TRUE if more than 500 anomalous user events are found. ConfidenceEventsExportDTO
startTimeAfter Start interval for retrieving events. String (format : yyyy-MM-dd HH:mm:SS)
endTimeBefore End interval for retrieving events. String (format : yyyy-MM-dd HH:mm:SS)

Example Response Metadata

{

"status": 0,

"listOfConfidenceEventsExportEntries": {

"confidenceEventsExportEntries":

[

{

...

}

],

"maxEventsExceeded": false

},

"startTimeAfter": "2021-01-13 15:52:828",

"endTimeBefore": "2021-01-14 15:52:828"

}

Response Data

Name Description Type
user_email User email used for authentication. String
customer_name

Company name specified in My Account > Company Settings.

 String
event_transaction_id Identifies each user event log message. Long
confidence The user's overall identity confidence score, which is influenced by the user's separate scores for Device Confidence, Behavior Confidence, and Location Confidence. Double
threshold

Confidence scores higher than this threshold indicate high confidence, while lower scores indicate low confidence. The threshold calculation is based on information collected from all users within your company and adjusts over time as the Cloud Authentication Service learns about your users and as more users authenticate. The initial default threshold is 0.37. After at least 1,000 authentications have been reached, the threshold is updated daily.

Double
behavior_confidence Level of confidence based on attributes associated with the user's behavior. For example, this score is adjusted when the user successfully authenticates to access the same application within the same timeframe. Double
location_confidence Level of confidence based on attributes associated with the user's location. For example, this score is increased if the user successfully authenticates from the same location every day and decreased if the user successfully authenticates from different locations every day. Double
device_confidence Level of confidence based on attributes associated with the user's device. These attributes describe device characteristics and user behavior. The Device Confidence score starts at 0.0 if the user has not previously used the device and increases each time the user successfully authenticates from the same device. Double
event_at Date and time of user event log, in UTC timezone. Example: 2018-05-13T16:29:59.000 UTC ISO 8601 Date Time
top_contributors

If a user's overall Confidence score indicates low confidence, the API reports up to four factors that most contributed to lowering the score. These factors are listed in order from most impactful to less impactful. Factors that contribute to raising a user's overall score are not listed.

 List of Strings
severity The difference between the user’s Confidence score and the Confidence Threshold at the time of authentication. The larger the difference, the higher the degree of anomalous behavior. Double
maxEventsExceeded This flag is TRUE if more than 500 anomalous user events are found. Boolean