User Groups

User groups support adding or removing users in bulk from Projects, Datasets, and Ontologies within your Workspace. This page covers the full group workflow with the SDK: managing your organization’s members, creating and managing groups, managing group membership, and assigning users and groups to resources.

All examples authenticate with an SSH private key — replace <private_key_path> with the path to your key. See Authentication. US platform users should add domain="https://api.us.encord.com" to create_with_ssh_private_key.

Organization members

Before a user can be added to a group, they must be a member of your organization. Use these EncordUserClient methods to manage organization membership. Managing members requires organization admin permissions.

Role (`role_mnemonic_name`)	Description
`ADMIN`	Full administrative access. Only `internal` members can be admins.
`MEMBER`	Standard member.
`WORKFORCE_MANAGER`	Manages the annotation workforce.
`TASKER`	Annotator / task worker.

member_type is either "internal" (a member of your organization) or "external" (a collaborator, e.g. from another company).

Manage organization members

# 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>"
    )

# --- List organization members ---
for member in user_client.list_organisation_users():
    print(f"{member.email} | role: {member.role_mnemonic_name} | type: {member.member_type}")

# --- Add a member ---
# role_mnemonic_name and member_type are keyword-only.
# If the email has no Encord account, one is created and an onboarding email is sent.
user_client.add_organisation_user(
    "new.member@example.com",
    role_mnemonic_name="MEMBER",
    member_type="internal",
)

# --- Remove a member ---
# Membership is deleted immediately; resource unassignment is scheduled.
user_client.remove_organisation_user("former.member@example.com")

Create and manage groups

You can create and manage user groups directly with the SDK. The calling user is automatically added as a manager of any group they create.

You can also create user groups in the Encord platform.

Create and manage a group

# 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>"
    )

# --- Create a group ---
group = user_client.create_group("Radiology Reviewers", description="Clinical review team")
print(group.group_hash, group.name, group.created_at)

# --- Fetch a specific group by its hash ---
group = user_client.get_group("<group_hash>")

# --- Rename or re-describe a group ---
group.update_group(name="Radiology QA", description="Updated description")

# --- Delete a group (also revokes any access it granted to resources) ---
user_client.delete_group("<group_hash>")

Manage group membership

Add and remove the users that belong to a group. All emails must already belong to members of your organization (see Organization members).

Manage group membership

# 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>"
    )

# Get the group you want to manage
group = user_client.get_group("<group_hash>")

# --- Add members ---
group.add_users(["reviewer1@example.com", "reviewer2@example.com"])

# --- List members ---
for user in group.list_users():
    print(user.email)

# --- Remove members ---
group.remove_users(["reviewer2@example.com"])

List user groups

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

List all user groups in your Workspace

You can list all users groups that currently exist within your Workspace. 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 Workspace 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)

# 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 Dataset. Replace <dataset_hash> with the hash for your Dataset
dataset = user_client.get_dataset("<dataset_hash>")

# List Dataset Groups
for dataset_group in dataset.list_groups():
    print(dataset_group)

# 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 Ontology. Replace <ontology_hash> with the hash for your Ontology
ontology = user_client.get_ontology("<ontology_hash>")

# List Dataset Groups
for ontology_group in ontology.list_groups():
    print(ontology_group)

group_hash=UUID('fd299110-b10b-42c0-b014-8ffecb44ca6b') name='Annotators1' description='annotator_team_1' created_at=datetime.datetime(2022, 10, 28, 10, 1, 44, 664227)
group_hash=UUID('fe8ac5dc-6ac4-489c-a034-917752c341a4') name='Annotators2' description='annotator_team_2' created_at=datetime.datetime(2022, 10, 19, 16, 56, 13, 832372)

Assign users directly to Projects / Datasets

As well as adding whole groups, you can add individual users to a Project or Dataset and set the role they hold there. Adding a user who already has access leaves their existing role unchanged.

Projects

ProjectUserRole supports read-only viewers via VIEWER:

`ProjectUserRole`	Description
`ADMIN`	Full project access.
`ANNOTATOR`	Can annotate.
`REVIEWER`	Can review.
`ANNOTATOR_REVIEWER`	Can annotate and review.
`TEAM_MANAGER`	Manages the project team.
`VIEWER`	Read-only access.

Manage project users

# Import dependencies
from encord import EncordUserClient, Project
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>"
    )

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

# --- Add users with a role ---
added = project.add_users(
    ["annotator@example.com", "observer@example.com"],
    ProjectUserRole.ANNOTATOR,
)
for user in added:
    print(user.user_email, user.user_role)

# --- Add a read-only viewer ---
project.add_users(["stakeholder@example.com"], ProjectUserRole.VIEWER)

# --- List users ---
for user in project.list_users():
    print(user.user_email, user.user_role)

# --- Remove users ---
project.remove_users(["observer@example.com"])

Datasets

DatasetUserRole is either ADMIN or USER.

Manage dataset users

# 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>"
    )

# Specify the Dataset. Replace <dataset_hash> with the hash for your Dataset
dataset = user_client.get_dataset("<dataset_hash>")

# --- Add, list, and remove users ---
dataset.add_users(["curator@example.com"], DatasetUserRole.USER)
for user in dataset.list_users():
    print(user.user_email, user.user_role)
dataset.remove_users(["curator@example.com"])

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)

# 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.TEAM_MANAGER)

# 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.ANNOTATOR_REVIEWER)

# 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.ANNOTATOR)

# 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.REVIEWER)

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)

# 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.USER)

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)

# 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.USER)

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

# 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 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>"]  # Include as many group names as needed.
group_hashes = [group.group_hash for group in groups if group.name in group_names]
dataset.remove_group(group_hashes)

# 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 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>"]  # Include as many group names as needed.
group_hashes = [group.group_hash for group in groups if group.name in group_names]
ontology.remove_group(group_hashes)

Get Started

General

Data

Ontologies

Projects

Labels

DICOM

Organization members

Create and manage groups

Manage group membership

List user groups

List all user groups in your Workspace

List user groups for Projects / Datasets / Ontologies

Assign users directly to Projects / Datasets

Projects

Datasets

Add user groups

Add user group to Projects

Add user group to Datasets

Add user group to Ontologies

Remove user groups from Projects / Datasets / Ontologies

​Organization members

​Create and manage groups

​Manage group membership

​List user groups

​List all user groups in your Workspace

​List user groups for Projects / Datasets / Ontologies

​Assign users directly to Projects / Datasets

​Projects

​Datasets

​Add user groups

​Add user group to Projects

​Add user group to Datasets

​Add user group to Ontologies

​Remove user groups from Projects / Datasets / Ontologies

Organization members

Create and manage groups

Manage group membership

List user groups

List all user groups in your Workspace

List user groups for Projects / Datasets / Ontologies

Assign users directly to Projects / Datasets

Projects

Datasets

Add user groups

Add user group to Projects

Add user group to Datasets

Add user group to Ontologies

Remove user groups from Projects / Datasets / Ontologies