Group

The IronNode 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.

Group 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.

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

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

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.addAsAdmin] boolean Whether to add the calling user as an administrator of the group. Defaults to true.
[options.addAsMember] boolean Whether to add the calling user as a member of the group. Defaults to true.
[options.groupName] string Readable name of the group. This data will be stored unencrypted.
[options.memberList] Array<string> Optional array of user IDs to add as members to the group.
[options.adminList] Array<string> Optional array of user IDs to add as administrators to the group.
[options.needsRotation] boolean Optional flag to create the group with pending private key rotation.
[options.ownerUserId] string Optional user ID that will be assigned the role of group owner. If this field is not specified the calling user will be the group owner by default. If the calling user does not want to be an administrator of the group a user ID must be provided in this field, as the group must contain an owner.

Response

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

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

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

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

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.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 curretly 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

Parameter Name Value Description
groupID string ID of the group.

Response

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

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

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
}