Risk Cloud API: Grant Users Record Access

Updated on: June 05, 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.

This access can also be granted to individual users as well, where users can be granted access to a record individually. This appears in the Risk Cloud web application under Record Access > Users for User Group enabled records.

On the API level, this list of users is represented as a "Default User Group", a unique type of user group that is uniquely create for each individual record.

Additionally, the Risk Cloud API enables you to dynamically grant users access to records via default user groups.

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

Update Default User Group

The User Group API offers the following Update Default User Group endpoint, allowing you to set or remove users from a record's default user group.

PATCH/api/v1/userGroups/recordDefault/{user-group-id}?record={record-id}

Use Cases

Get Record ID

The record-id can be obtained from the Risk Cloud web application, emails, or via the Risk Cloud API.

Using the Risk Cloud application

The most straightforward way to find the record ID for record-id is to open the desired record in the Risk Cloud web application, then take the ID from the end of the URL.

https://your-company.logicgate.com/records/{record-id}

Using email

The Contextual Notifications feature offers the ability to set Custom Fields and System Fields in outbound emails. As a result, Record ID is a System Field that can be included in outbound emails from the Risk Cloud. This Record ID could in turn be parsed from the email for use in the following Post Record Comment API request.

Using the Risk Cloud API

Reference the article Risk Cloud API: Record Search to obtain record IDs via the Risk Cloud API.

Get Default User Group

When a record is created, a default User Group is added that is used for granting specific users access to the record. It's important to preserve this User Group when adding and removing additional User Groups.

In order to preserve this User Group when updating User Groups on a record, the default User Group is needed, which can be obtained from the following internal Risk Cloud API endpoint.

For record-id, use the record ID obtained in the step above.

GET/api/v1/internal/userGroups/default?record={record-id}

Response

The default User Group ID can be located as the value of the id property in the response object.

{
  "id": "a1b2c3d4",
  "recordDefault": true,
  "title": " Default Group",
  "users": []
}

Get User IDs

The user IDs to add to the default user 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 ...
}

Update Default User Group

With the default User Group ID and the User IDs of users to add to the default user group, the users can be added via the following API endpoint and request body payload.

Additionally, if you wish to remove users from the default user group, you may omit the user objects from the request payload to have them removed.

PATCH/api/v1/userGroups/recordDefault/{user-group-id}?record={record-id}

Request Body

Use the record ID obtained in the first step for the record ID in the record query parameter.

Use the full payload from the Get Default User Group response, including id, name, users, and recordDefault  as the basis of the request body.

Modify the users array with user objects containing the user IDs of the users you wish to grant access to the record. The id, status of Active, and valueType of User should be present in the user objects.

{
    "recordDefault": true,
    "users": [
        {
            "status": "Active",
            "valueType": "User",
            "id": "{user-id}"
        }
    ],
    "id": "{user-group-id}",
    "title": " Default Group"
}

Response

A 200 response confirming that the Default User Group was updated. Upon refreshing the record in the Risk Cloud Web Application, the users are updated accordingly.