Cloud Administration Anomalous Users APICloud 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.
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 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 ParametersRequest 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 ParametersExample 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 SpecifiedExample 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 MetadataResponse Metadata
Name | Description | Type |
---|---|---|
status |
The Cloud Authentication Service sends the following status codes when processing input parameters:
|
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 MetadataExample Response Metadata
{
"status": 0,
"listOfConfidenceEventsExportEntries": {
"confidenceEventsExportEntries":
[
{
...
}
],
"maxEventsExceeded": false
},
"startTimeAfter": "2021-01-13 15:52:828",
"endTimeBefore": "2021-01-14 15:52:828"
}
Response DataResponse 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 |