User Groups

User Groups API


We usually interpret a user group as precisely what the name says: a group of users. For example, you may want to group users by their home country or any other characteristic. Read more about this topic in the user group feature guide.



To create a user group, you simply need to define a name and reference. The API detail for the method can be find here (opens in a new tab).

await client.asSuperAdmin().createUserGroup(
  { userGroup: 
      { name: 'xyz789', reference: 'xyz789' }
namestringThe name of the user group. For instance “My Team”
referencestringReference to an object on the project-side. This could be the ID of an entity in your database


The addUsersToUserGroup() (opens in a new tab) API will add users to a user group, you can use this mutation with ROQ Node.js SDK or GraphQL:

await client.asSuperAdmin().addUsersToUserGroup(
  { userGroupId: "abc123", 
    userIds: ["abc123", '321cba'] 
userGroupIduuidThe ID of the user group.
userIdarrayThe array of the user ids that will be added to the group


The updateUserGroup() (opens in a new tab) API will update the user group data based on the user group id.

const updateGroup = await roqClient.asSuperAdmin().updateUserGroup({
  id: "42103455-1e00-41bf-9714-c70a8c17caf9",
  userGroup: {
    name: "Video Creator",
    reference: "video-creator-group"
iduuidThe ID of the user group group to be updated
userGroup:namestringThe new user group name will replacing the old one
userGroup:referencestringThe new user group name reference replacing the old one


ROQ also provides an API to remove users from a user group. You can use the removeUsersFromUserGroup with Node.js SDK or GraphQL query. The API documentation is here (opens in a new tab).

const removeStatus = await roqClient.asSuperAdmin().removeUsersFromUserGroup({
  userGroupId: "554a2843-66dd-4c9a-adc1-0c48484591b6",
  userIds: ["244784e9-3b56-421c-925d-d9bbefab2de4"]

The above method will return a boolean value of true if the removal is successful:

{ removeUsersFromUserGroup: true }
userGroupIduuidThe ID of the user group group
userIdsarrayThe ID of users to be removed from a user group



With the userGroups() (opens in a new tab) API you can get all the registered user groups.

To see user groups with users you run a query like this:

await client.asSuperAdmin().userGroups({
  filter: {
    name: {
      like: "moderator"
  withUsers: true 

Another way to fetch users by a user group could look like:

await client.asSuperAdmin().users({ filter: { 
    userGroupId: {equalTo: "123" } 
limitintegerLimit the user groups result group.
filterarrayFilter the user groups based on the id, name, etc. Please look into the UserGroupFilterArgType (opens in a new tab)


The userGroup() (opens in a new tab) API is used to get the information about the specific user group.

const groupId = "42103455-1e00-41bf-9714-c70a8c17caf9";
const mygroup = await roqClient.asSuperAdmin().userGroup(groupId);
iduuidThe ID of the user group.