Cloud Administration Add/Remove High-Risk User API

Use the Cloud Administration Add/Remove High-Risk User List API to add or remove one or more users from a high-risk user list. You can determine authentication and access requirements for users who are identified as high risk. These might be users whose accounts have been compromised, or for whom a third-party security information and event management (SIEM) solution, such as SecurID NetWitness, has detected suspicious activity.

Note: This API is available only for Premium Edition.

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 must use an API key that is associated with the Super 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 to add or remove one or more users from the high-risk user list.

Note: The high-risk user list supports user emails. The sAMAccountName attribute is not supported.

Method Request URL Response Content Type Response Body Response Codes
PUT /AdminInterface/restapi/v1/users/highrisk
application/json

List of user emails that failed to update, or none if all succeeded.

200, 207, 403, 500

Example Request Body

The following example displays a request.

PUT /AdminInterface/restapi/v1/users/highrisk

Accept: application/json

Authorization: Bearer <JWT token>

Request Body Parameters

The following table describes the request body parameters.

Request Parameter Required Description Type
action Yes Add or remove. Case insensitive. String
users Yes

List of users identified as described in User Identification. Case insensitive. Maximum number of users is 100.

Array

User Identification

The request can identify users as described in the following table. Make sure the appropriate identity source attributes are configured as described in Add, Delete, and Test the Connection for an Identity Source in the Cloud Authentication Service and Directory Server Attributes Synchronized for Authentication.

User Identifier Description
Email address The user's unique email address.

Primary Username or UID

For Active Directory, use sAMAccountName. For LDAP directories, use UID.
Alternate Username LDAP attribute containing the user's alternate username. For example, this can be used to represent the UserPrincipalName in Azure Active Directory.

When the Cloud Authentication Service receives a list of users, it first searches for users' email addresses. If it cannot find a user's email address, it searches for the user's Primary Username or UID, and finally for the Alternate Username. Searching by Primary Username or Alternate Username can result in multiple conflicting matches. When searching by Primary Username, the Cloud Authentication Service selects the user with the latest creation entry. When searching by Alternate Username, no user is selected and the API responds with an HTTP failed status code.

Example Request Body

The following example displays a request body.

{ "action": "add",

"users": [

"user.one@mycompany.com",

"user.two@mycompany.com",

"user.three@mycompany.com"

]

}

Response

The following table lists the response scenarios.

Scenario Response Code Response Body
Successfully updated all users in the request. 200 OK. No body is returned.
Partially successful in updating users in the request. 207

Multi-status list of user emails that did not update from the request. See Cloud Administration Add/Remove High-Risk User API.

Invalid request body parameters. 400

Bad request caused by one of the following:

Invalid property.

Invalid or missing action code.

Empty list of emails.

Number of emails exceeds maximum allowed value of 100.

Not authorized to perform the request. 403 Forbidden.
User not found in the identity source. 404 User not found.
Multiple users were found for the alternate username. 409 Multiple users were found for the user identifier
Unexpected error. 500 Internal server error.

Multi-Status Objects Response

When a partial success occurs, each failed user is listed in the response, along with the status code.

Example Partial Success Response Body

The following example displays a partial success response body.

{

"users": [

{

"id": "user.one@company.com",

"statusCode": 404,

"error": "User not found"

},

{

"id": "user.two@company.com",

"statusCode": 409,

"error": "Multiple users were found for the user identifier"

}

]

}

Property Response Descriptions

The following table describes properties used in the response.

Property Description Data Type
user

User's email address.

String
statusCode HTTP status code for failed operation 400 or 500. See Cloud Administration Add/Remove High-Risk User API String
error Error message describing the failed operation. String