Group

The IronWeb SDK group namespace provides methods to manage your cryptographic groups. These methods can be used to retrieve existing groups, create new groups, and manage the administrators and members of your group. The SDK object in the examples below refers to the object that is returned once the initialization Promise has been resolved.

Groups contain users in three different categories:

• Administrator: Group administrators have the ability to add and remove both group members and administrators. Group administrators cannot decrypt documents encrypted to the group.
• Member: Group members have the ability to decrypt any document encrypted to the group. Group members can also remove themselves from a group.
• Owner: The group owner has all the same permissions of any other group administrator but cannot be removed as an administrator of the 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.

JSON

{
    "result": [
        {
            "groupID": string,
            "groupName": string | null,
            "created": string,
            "updated": string,
            "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

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.

JSON

{
    "groupID": string,
    "groupName": string|null,
    "created": string,
    "updated": string,
    "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,
//Will only be returned if user is an administrator of the group
    "needsRotation": boolean | undefined
}

group.create()

IronWeb.group.create([options])

Creates a new group with optional initial admins, members, ID and name. By default, the calling user will become the group owner as well as a member of the group. The group owner has the same permissions as any other group administrator, but cannot be removed as an administrator from the group. Alternatively, on creation of the group another user can be specified as the group owner by setting the options.ownerUserId field. The group owner cannot by default decrypt data encrypted to the group unless they are also a member of the group.

Parameters

Response

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

JSON

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

group.update()

IronWeb.group.update(groupID, options)

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

Parameters

Response

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

JSON

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

group.addAdmins()

IronWeb.group.addAdmins(groupID, userList)

Adds the provided list of user IDs as administrators of the provided group. The calling user must be an administrator of the group.

Parameters

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.

JSON

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

group.removeAdmins()

IronWeb.group.removeAdmins(groupID, adminList)

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

Parameters

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.

JSON

{
    "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

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.

JSON

{
    "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

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.

JSON

{
    "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

Response

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

group.rotatePrivateKey()

IronWeb.group.rotatePrivateKey(groupID)

Rotate the group’s private key, but leave the public key the same. Only administrators of the group are allowed to rotate the group private key. Calls to rotate the group key can be done at any time, regardless of whether the group record is currently flagged for rotation. Group private key rotation does not affect member or administrator group access. Group rotation requires recalculating keys for each group administrator so while this operation will be seamless to all administrators and members, it can possibly take a long time to complete if there are numerous group administrators.

Parameters

Response

Returns a Promise that resolves with a boolean that indicates if the group has a pending need for private key rotation.

JSON

{
    "needsRotation": boolean
}

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

Response

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

JSON

{
    "id": string
}