Risk Cloud API: Create User Groups

Updated on: April 19, 2024

User Groups give you the ability to provide more detailed access to particular records in your application, similar to how permission sets allow you to restrict access on steps. User Group access will allow you to "tag" specific users or User Groups (pre-defined groups of users) to a record and restrict access to only those users and User Groups tagged. Additionally, the Risk Cloud API enables you to dynamically create User Groups as a part of custom integrations.

Obtain your API Access Token or pull the Risk Cloud Postman Collection to get started.

Create User Group Endpoint

The internal User Group API offers the following Create User Group endpoint, allowing you to create User Groups from a title and the IDs of users to add to the group alone.

POST/api/v1/internal/userGroups

This endpoint returns a summary of the created group, including its name and ID.

Use Cases

Get User IDs

The user IDs to add to the newly created group can be obtained from either you Risk Cloud web app environment directly or from the Risk Cloud API.

Get User ID (Web App Environment)

A user ID can be located within you Risk Cloud web app environment in the following location:

  • Navigate to Admin > Users
  • Search for an select a user by clicking their email
  • The user ID can be found in under the User ID label

Get User ID (Risk Cloud API)

A user ID can be located via the User API, specifically in the id property of the returned user objects.

To obtain all users, reference the article Risk Cloud API: Viewing Users.

To obtain a user ID by a particular email, use the following internal User API endpoint.

GET/api/v1/internal/users?search-type=EMAIL&query={email}

Response

{
  "content": [
    {
      "id": "a1b2c3d4",
      "email": "[email protected]",
      // ... truncated ...
    }
  ],
  "pageable": {
    // ... truncated ...
  },
  // ... truncated ...
}

Create User Group

With the User IDs of the users to added to the new User Group, the User Group can be created via the following API endpoint and request body payload.

POST/api/v1/internal/userGroups

Request Body

Note that "status": "Active" is required to accompany all user IDs. Populate the User IDs obtained above into JSON objects and add them to the users array. Additionally set the title to the desired title of the user group, which is recommended to be unique.

{
    "users": [
        {
            "status": "Active",
            "id": "user-id-1"
        },
        {
            "status": "Active",
            "id": "user-id-2"
        }
    ],
    "title": "New User Group Title"
}

Response

The response contains the newly created User Group's ID, the title, and an indicator that it's not a record default User Group (which is expected).

{
    "id": "user-group-id",
    "recordDefault": false,
    "title": "New User Group Title"
}