Group

A groups helps to gain access to resources for some users. As long as a user is in a group he/she can access all protected content.

Sentc provides simple checks for your backend to see if a user is in a group. Just link resources with the group.

Create a group

Call createGroup() from the User object after logging in a user.

//the user obj from login
const group_id = await user.createGroup();

When you use your own backend, make a POST request to our API (https://api.sentc.com/api/v1/group) from your backend. Don't forget to include the Authorization header with the JWT.

Fetch a group

To access the data of a group, a user can fetch them from the API. To fetch a group, use the group ID as a parameter. This returns a group object that can be used for all group-related actions.

//the user obj from login
const group = await user.getGroup(group_id);

Get all groups

To retrieve all group IDs where the user is a member, use this function:

//the user obj from login
const groups = await user.getGroups();

The groups are an array and each item is from type GroupList

interface GroupList
{
	group_id: string,
	time: number,
	joined_time: number,
	rank: number,
	parent?: string
}

To fetch more groups use pagination and pass in the last fetched item:

const last_item = groups[groups.length - 1];

//the user obj from login
const groups_page_two = await user.getGroups(last_item);

Group rank

The user's rank in a group determines their level of access. An administrator or creator has full control, while a regular member may have limited privileges such as being unable to accept join requests. Ranks are assigned as numbers ranging from 0 to 4

  • 0 is the creator of a group and has full control
  • 1 is an administrator and has nearly full control, except for removing the creator
  • 2 can manage users: accept join requests, send invites, change user ranks (up to rank 2), and remove group members (with a rank of 2 or lower)
  • 3 and 4 are normal user ranks. A new member is automatically assigned rank 4. Rank 3 can be used for other actions, such as content management.

To change a user's rank, you need the Sentc API user ID and assign a new rank number:

//we set the rank to 2 here
await group.updateRank("internal_user_id", 2);

If you have your own backend and want to change a user's rank using a secret token, use this function to obtain the input data for the API. To change the rank, make a PUT request to the following URL with the group ID and the input data from your backend: https://api.sentc.com/api/v1/group/<the_group_id>/change_rank

//we set the rank to 2 here
const input = await group.prepareUpdateRank("internal_user_id", 2);

See more at own backend

Invite more user

There are two methods to add more users to a group: by invitation or by join request.

Invite a user

Inviting a user is done by a group administrator (ranks 0-2) to a non-group member. The non-group member can choose to accept or reject the invitation.

Optional, a rank can be set for the invited user.

await group.invite("internal_user_id");

//with optional rank, in this case rank 1
await group.invite("internal_user_id", 1);

A user can get invites by fetching invites or from init the client.

const invites = await user.getGroupInvites();

The invites are an array and each item is from type GroupInviteListItem

interface GroupInviteListItem
{
	group_id: string,
	time: number
}

To fetch more invites just pass in the last fetched item from the function:

const last_item = invites[invites.length - 1];

const invites = await user.getGroupInvites(last_item);

To accept an invitation as user call his function with the group id to accept:

The group id can be got from the GroupInviteListItem

await user.acceptGroupInvite("group_id");

Or reject the invite

The group id can be got from the GroupInviteListItem

await user.rejectGroupInvite("<group_id>");

Join request

A non-group member can request to join a group by calling this function. A group administrator can choose to accept or reject the request.

await user.groupJoinRequest("<group_id>");

To fetch the join requests as a group admin use this function:

const req = await group.getJoinRequests();

The requests are an array and each item is from type GroupJoinReqListItem

interface GroupJoinReqListItem
{
	user_id: string,
	time: number
}

To fetch more requests just pass in the last fetched item from the function:

const last_item = req[req.length - 1];

const req = await group.getJoinRequests(last_item);

A group admin can accept the request like this:

The user id can get from the GroupJoinReqListItem.

await group.acceptJoinRequest("user_id");

//with optional rank, in this case rank 1
await group.acceptJoinRequest("user_id", 1);

Or reject it:

The user id can get from the GroupJoinReqListItem.

await group.rejectJoinRequest("user_id");

A user can fetch the sent join requests:

interface GroupInviteListItem
{
	group_id: string,
    time: number
}

const list: GroupInviteListItem[] = await user.sentJoinReq();

//to load more use the last item of the pre fetch
const list_page_two: GroupInviteListItem[] = await user.sentJoinReq(list[list.length -1]);

A user can also delete an already sent join request. The group id can be fetched from the sentJoinReq() function.

await user.deleteJoinReq("<group_id>");

Auto invite

A group administrator can use this function to automatically invite and accept a non-group member, without requiring any additional actions from the new member.

await group.inviteAuto("user_id");

Stop invite

Calling this function will prevent non-group members from sending join requests and group administrators from inviting more users. This feature can be useful for one-on-one user sessions. After automatically inviting the other user, you can use this function to close the invitation process.

await group.stopInvites();

Get group member

The fetch uses pagination to not fetch all members at once.

const members = await group.getMember();

Members are an array and each item is from type GroupUserListItem.

interface GroupUserListItem 
{
	user_id: string,
	rank: number,
	joined_time: number,
}

To fetch more use the last fetched member item:

Members are from type GroupUserListItem.

const last_item = members[members.length -1];

const members_page_two = await group.getMember(last_item);

Delete group member

A group member with a rank higher than 2 (0, 1, 2) can use this function to delete another member with the same or lower rank. However, a member cannot delete themselves using this function.

await group.kickUser("internal_user_id");

Leave a group

Every member can leave a group except the creator.

await group.leave();

Parent and child group

A group can be set as a child of a parent group, creating a hierarchical structure of groups. All members of the parent group are automatically granted access to the child group(s) with the same rank as in the parent group. When a new member joins the parent group, they are automatically added as a member to all child groups. Multiple child groups can also be created:

parent
    child from parent
        child from child from parent
            child from child from parent
    child from parent

To create a child group just call group create in the parent group not in the user scope

const group_id = await group.createChildGroup();

//get the group from a user, if not loaded, the parent group will be loaded automatically
const group = await user.getGroup(group_id);

//or get it from the parent group
const group_from_parent = await group.getChildGroup(group_id);

To get all children of the first level use the getChildren() function in the group object.

It returns a List with the child group id, the child group created time and the parent id.

const children: GroupChildrenListItem[] = await group.getChildren();

//to get the 2nd page pass in the last child
const children_page_two: GroupChildrenListItem[] = await group.getChildren(children[children.length -1]);

Connected groups

A group can also be a member in another group which is not a child of this group. Connected groups can also have children or be a child of a parent. Groups with access to the connected group got also access to all the child groups. A connected group can't be member in another group, so only normal groups can be a member in a connected group. Normal groups can't have other groups as member except their child groups.

A connected group can be created from a normal group.

const group_id = await group.createConnectedGroup();

To fetch the connected group you can either fetch it from the group or from the user. From user requires the group id which was connected to the connected group.

// from the group
const connected_group = await group.getConnectedGroup(connected_group_id);

//from the user, the group id is needed
const connected_group_by_user = await user.getGroup(connected_group_id, group_id);

When accessing a child group of a connected group, make sure to load the parent group first which is connected to the user group.

To get all connected groups to a group use the getGroups() function in the group object. It returns a List of groups with the group id and the group created time.

const connected_groups: GroupList[] = await group.getGroups();

//to get the next pages, use the last item.
const connected_groups_page_two: GroupList[] = await group.getGroups(connected_groups[connected_groups.length-1]);

Like users, groups can also send join requests to connected groups.

await group.groupJoinRequest("<group_id>");

Groups can also fetch the sent join requests.

const list: GroupInviteListItem[] = await group.sentJoinReq();

//to load more use the last item of the pre fetch
const list_page_two: GroupInviteListItem[] = await group.sentJoinReq(list[list.length -1]);
interface GroupInviteListItem
{
	group_id: string,
    time: number
}

A group can also delete an already sent join request. The group id can be fetched from the sentJoinReq() function.

await group.deleteJoinReq("<group_id>");

Child groups vs connected groups, when use what?

The problem with child groups is that it is a fixed structure and can't be changed in the future.

A connected group can be helpfully if you want to give a group (and all its parents) access to another group (and all its children). This can be used to connect resources and users together, e.g.:

  • user in department groups (hr, marketing, development)
  • resources like customer, employee data, devops secrets
  • let dev manager access group employee data and devops secrets and marketing access customer.
  • Inside each department group there are multiple child groups for each sub department. If the manger is in the parent group, he/she can access every subgroup

The recommended approach is to use normal groups for user and connected groups for resources.

parent
    child from parent                       -->              connected group
        child from child from parent                           child from connected group
            child from child from parent
    child from parent

Delete a group

Only the creator (rank 0) or the admins (rank 1) can delete a group.

await group.deleteGroup();
Last Updated: