Group

The IronWeb SDK group namespace provides methods to manage your cryptographic groups. This namespace can be used to retrieve existing groups, create new groups, and manage the administrators and members of your group.

Note: The SDK must be initialized before these methods can be called.

group.list()

IronWeb.group.list()

Gets the list of groups that the current user is either a member or administrator of.

Parameters

None

Response

Returns a Promise which resolves with the list of groups the user is a member or administrator of.

{
    "result": [
        {
            "groupID": string,
            "groupName": string | null,
            "isAdmin": boolean,
            "isMember": boolean
        }
    ]
}

group.get()

IronWeb.group.get(groupID)

Retrieves details about a group by its ID. Result will optionally include the IDs of the admins and members of the group but only if the requesting user is an administrator or member of the group.

Parameters

Parameter Name Value Description
groupID string ID of the group to retrieve.

Response

Returns a promise that resolves with details about the group. If the user is an administrator of the group they'll also get the list of IDs for current users and administrators of the group.

{
    "groupID": string,
    "groupName": string|null,
    "isAdmin": boolean,
    "isMember": boolean,
    //Will only be returned if user is an administrator or member of the group
    "groupAdmins": Array<string>|undefined,
    "groupMembers": Array<string>|undefined,
}

group.create()

IronWeb.group.create([options])

To create a new group call the create method. The creator of the group will automatically become an administrator and by default a member of the group. Allows optionally setting a readable name for the group as well as configuring whether or not the user should be added as a member.

Parameters

Parameter Name Value Description
[options.groupID] string Optional unique ID of the group. Group IDs must be unique across all groups in a Segment. Group IDs cannot contain the comma character.
[options.addAsMember] boolean Whether to add the creator of the group as a member of the group. Defaults to true.
[options.groupName] string Readable name of the group. This data will be stored unencrypted.

Response

Returns a Promise that will resolve with information about the newly created group.

{
    "groupID": string,
    "groupName": string|null,
    "isAdmin": boolean,
    "isMember": boolean,
    "groupAdmins": Array<string>,
    "groupMembers": Array<string>,
}

group.update()

IronWeb.group.update(groupID, options)

Update a group given its ID. Currently only allows changing or clearing the group name.

Parameters

Parameter Name Value Description
groupID string ID of the group to update.
options.groupName string | null New name of the group or null to clear the groups name. Required field as it's currently the only field to update on a group.

Response

Returns a Promise that will resolve with information about the updated group

{
    "groupID": string,
    "groupName": string|null,
    "isAdmin": boolean,
    "isMember": boolean,
}

group.addAdmins()

IronWeb.group.addAdmins(groupID, userList)

By default the creator of a group is the administrator of that group. The addAdmins method adds one or more admins to the targeted group at a time. Add additional administrators to the group. The calling user must be an administrator of the provided group ID. Administrators can add and remove members as well as add and remove other administrators except for the group creator. Group administrators cannot by default decrypt data encrypted to the group unless they are also a member of the group.

Parameters

Parameter Name Value Description
groupID string ID of the group.
userList Array<string> Array of user IDs to add as administrators to the group.

Response

The addAdmins method returns a Promise that will resolve with two lists, succeeded, an array that contains the ids of the users where are successfully added as admins of the group, and failed, an array of error objects containing an error code and message describing why an user could not be added as an administrator to the group.

{
    "succeeded": Array<string>,
    "failed": [{
        "id": string,
        "error": string,
    }],
}

group.removeAdmins()

IronWeb.group.removeAdmins(groupID, adminList)

Removes the provided list of user IDs as administrators of the group. Only administrators of the group are allowed to remove other administrators. The group's creator cannot be removed as an administrator from the group.

Parameters

Parameter Name Value Description
groupID string ID of the group.
adminList Array<string> List of administrator user IDs to remove.

Response

Returns a Promise that will resolves with a list of administrators who were successfully removed and a list of administrators who were not removed to the group.

{
    "succeeded": Array<string>,
    "failed": [{
        "id": string,
        "error": string,
    }],
}

group.addMembers()

IronWeb.group.addMembers(groupID, userList)

Add additional members to the group. Members of the group can decrypt any documents that have been granted access with the group (regardless of when the document access was granted) as well as share other documents with the group. Only administrators of the group are allowed to add additional members.

Parameters

Parameter Name Value Description
groupID string ID of the group.
userList Array<string> List of user IDs to add as members to the group.

Response

Returns a Promise that resolves with a list of members who were successfully added and a list of users who were not added to the group.

{
    "succeeded": Array<string>,
    "failed": [{
        "id": string,
        "error": string,
    }],
}

group.removeMembers()

IronWeb.group.removeMembers(groupID, memberList)

Remove the provided list of users as members from the group. Only administrators of the group are allowed to remove group members.

Parameters

Parameter Name Value Description
groupID string ID of the group.
memberList Array<string> List of user IDs to remove as members from the group.

Response

Returns a Promise that resolves with a list of members who were successfully removed and a list of users who failed to be removed to the group.

{
    "succeeded": Array<string>,
    "failed": [{
        "id": string,
        "error": string,
    }],
}

group.removeSelfAsMember()

IronWeb.group.removeSelfAsMember(groupID)

Every user has the ability to remove themselves at anytime from a group. Allows a member of a group to remove themselves from the group. The user doesn't have to be a group administrator in order to remove themselves as a member.

Parameters

Parameter Name Value Description
groupID string ID of the group.

Response

Returns a Promise that will resolve when the authenticated user is removed as a member from the group.

group.delete()

Warning: Deletion of a group will cause all documents encrypted to that group to no longer be decryptable. Caution should be used when deleting groups.
IronWeb.group.delete(groupID)

Deletes a group.

Parameters

Parameter Name Value Description
groupID string ID of the group to delete.

Response

Returns a Promise that resolves with the ID of the group that was successfully deleted.

{
    "id": string
}