User groups support adding or removing users in bulk from Projects, Datasets, and Ontologies within your Organization.
Create user groups using the Encord platform.

​
List user groups

Listing user groups returns a list of all user group names.

​
List all user groups in your Organization

You can list all users groups that currently exist within your Organization. In the following script, ensure that you replace <private_key_path> with the path to your private key. 
# Import dependencies
from encord.user_client import EncordUserClient

# Authenticate using the path to your private key. Replace \<private_key_path> with the path to your private key.
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# List all groups for the Org your user belongs to
user_client.list_groups()

​
List user groups for Projects / Datasets / Ontologies

You can list all existing user groups for a specific Project. In the following script, ensure that you:
  • Replace <private_key_path> with the path to your private key.
  • If you are using the Project script, replace <project_hash> with the hash of the Project you want to list user groups for.
  • If you are using the Dataset script, replace <dataset_hash> with the hash of the Dataset you want to list user groups for.
  • If you are using the Ontology script, replace <ontology_hash> with the hash of the Ontology you want to list user groups for.
# Import dependencies
from encord.user_client import EncordUserClient

# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# Specify the Project. Replace <project_hash> with the hash for your Project
project = user_client.get_project("<project_hash>")

# List Project Groups
for project_group in project.list_groups():
    print(project_group)

​
Add user groups

User groups can be added to Projects, Datasets, and Ontologies.

​
Add user group to Projects

Use the following scripts to add user groups to a Project.
Only group members are added, not group managers.
In the following scripts, ensure that you:
  • Replace <private_key_path> with the path to your private key.
  • Replace <project_hash> with the hash of the Project you want to add a user group to.
  • Replace <group_name1> and <group_name2> with the name of the user group(s) you want to add to the Project. You can add one or multiple groups to a Project at once.
The different tabs show how to assign different user roles to the user group being added. 
# Import dependencies
from encord import EncordUserClient
from encord.utilities.project_user import ProjectUserRole

# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# Add group to Project. Replace <project_hash> with the hash of the Project
project = user_client.get_project("<project_hash>")
groups = user_client.list_groups()

# Replace <group_name1> and <group_name2> with the name(s) of the group(s).
group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
group_hashes = [group.group_hash for group in groups if group.name in group_names]
project.add_group(group_hashes, ProjectUserRole.ADMIN)

​
Add user group to Datasets

User groups can be added to Datasets. In the following scripts, ensure that you:
  • Replace <private_key_path> with the path to your private key.
  • Replace <dataset_hash> with the hash of the Dataset you want to add a user group to.
  • Replace <group_name1> and <group_name2> with the name of the user group(s) you want to add to the Dataset. You can add one or multiple groups to a Dataset at once.
The different tabs show how to assign different roles to the user group being added to the Dataset. 
# Import dependencies
from encord import EncordUserClient
from encord.orm.dataset import DatasetUserRole

# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# Add group to Dataset. Replace <dataset_hash> with the hash of the Dataset.
dataset = user_client.get_dataset("<dataset_hash>")
groups = user_client.list_groups()

# Replace <group_name1> and <group_name2> with the name(s) of the group(s).
group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
group_hashes = [group.group_hash for group in groups if group.name in group_names]
dataset.add_group(group_hashes, DatasetUserRole.ADMIN)

​
Add user group to Ontologies

Use the following scripts to add user groups to Ontologies. In the following scripts, ensure that you:
  • Replace <private_key_path> with the path to your private key.
  • Replace <ontology_hash> with the hash of the Ontology you want to add a user group to.
  • Replace <group_name1> and <group_name2> with the name of the user group(s) you want to add to the Ontology. You can add one, or multiple groups to an Ontology at once.
The different tabs show how to assign different roles to the user group being added to the Ontology. 

# Import dependencies
from encord import EncordUserClient
from encord.utilities.ontology_user import OntologyUserRole

# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# Add group to Ontology. Replace <ontology_hash> with the hash of the Ontology.
ontology = user_client.get_ontology("<ontology_hash>")
groups = user_client.list_groups()

# Replace <group_name1> and <group_name2> with the name(s) of the group(s).
group_names = ["<group_name1>", "<group_name2>"]  # Add as many group names as needed.
group_hashes = [group.group_hash for group in groups if group.name in group_names]
ontology.add_group(group_hashes, OntologyUserRole.ADMIN)

​
Remove user groups from Projects / Datasets / Ontologies

User groups can be removed from Projects, Datasets, and Ontologies individually, or in bulk.
Admins can only be removed from Projects, Datasets, or Ontologies by Organization admins.
In the following scripts, ensure that you:
  • Replace <private_key_path> with the path to your private key.
  • If using the Project script, replace <project_hash> with the hash of the Project you want to remove user groups from.
  • If using the Dataset script, replace <dataset_hash> with the hash of the Dataset you want to remove user groups from.
  • If using the Ontology script, replace <ontology_hash> with the hash of the Ontology you want to remove user groups from.
  • Replace <group_name1> and <group_name2> with the name of the user group(s) you want to remove from the Project. You can remove one, or multiple groups from a Project at once.
# Import dependencies
from encord import EncordUserClient

# Authenticate using the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>"
    )

# Remove group from Project. Replace <project_hash> with the hash of the Project
project = user_client.get_project("<project_hash>")
groups = user_client.list_groups()

# Replace <group_name1> and <group_name2> with the name(s) of the group(s).
group_names = ["<group_name1>", "<group_name2>"]  # Include as many group names as needed.
group_hashes = [group.group_hash for group in groups if group.name in group_names]
project.remove_group(group_hashes)