Docs
Data Control Platform
SDKs
NodeJS
Group

Group

The IronNode 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. The SDK object in the examples below refers to the object that is returned once the initialization Promise has been resolved.

group.list()

SDK.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()

SDK.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. A flag denoting whether the group’s private key requires rotation will be returned if the calling user is an administrator 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.

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

group.create()

SDK.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.
`[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.
`[options.needsRotation]`	`boolean`	Set to true if the private key for this group should be rotated when one of the admins “takes control” of the group. The main use case for this is a workflow that requires that the group be generated prior to the admins logging in for the first time. Optional, defaults to false.

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
}

group.update()

SDK.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`

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.rotatePrivateKey()

SDK.group.rotatePrivateKey(groupId)

Rotate the provided group’s private key, but leave the public key unchanged. There’s no black magic here! This is accomplished via multi-party computation with the IronCore webservice. The caller must be an admin of the group in order to rotate the private key. Group key rotation can occur at any time but should be done whenever a group is flagged as needing rotation.

Rotating a group’s private key requires a separate computation for every admin in the group; therefore, this operation can be computationally expensive if a group has a large number of admins.

Parameters

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

Response

Returns a Promise which resolves with an object that contains a flag that is true if additional private key rotation is needed.

JSON

{
    "needsRotation": boolean
}

group.addAdmins()

SDK.group.addAdmins(groupID, userList)

By default the creator of a group is an administrator of that group. The addAdmins method adds one or more admins 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. All group administrators can delete the group. 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.

JSON

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

group.removeAdmins()

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

JSON

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

group.addMembers()

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

JSON

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

group.removeMembers()

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

JSON

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

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.

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

JSON

{
    "id": string
}