Skip to content

Permissions

Flywheel controls access to data through a permission model applied at the group and project level. Understanding how the two levels interact is important for correctly managing user access.

Permission model overview

Flywheel has three built-in access levels:

Access level Description
read-only View containers, files, and metadata; no write access
read-write Create and modify containers and files
admin Full access, including managing project permissions

These access levels are used when adding users to a group. At the project level, access is controlled through roles rather than raw access levels. See Roles for details on defining and assigning custom roles.

Group-level vs. project-level permissions

Permissions set on a group give a user inherited access to all projects in that group. A project can also carry its own permission set, which applies in addition to (or in place of) the group-level assignment.

  • If a user has group-level access, they can see all projects in the group.
  • If a user has only project-level access, they can see that specific project without being a group member.
  • Project-level role assignments do not override group-level access; both apply.

Permission objects

Group-level and project-level permissions use different models.

Group permissions use an access level:

Field Description
id The user's email address (Flywheel user IDs are email addresses)
access Access level: "admin", "rw", or "ro"

Project permissions use role IDs instead of an access level:

Field Description
id The user's email address
role_ids List of one or more custom role IDs granted to the user

See Roles for details on defining and managing custom roles.

Reading permissions

Read permissions on a project
project = fw.get_project(project_id)
for perm in project.permissions:
    print(perm.id, perm.role_ids)
Read permissions on a group
group = fw.get_group(group_id)
for perm in group.permissions:
    print(perm.id, perm.access)

Adding a permission

Add a user to a project
project.add_permission(flywheel.RolesRoleAssignment(user_email, [role_id]))
Add a user to a group
fw.add_group_permission(
    group_id,
    flywheel.AccessPermission(id=user_email, access="rw"),
)

Updating a permission

To add or remove roles for a user already on a project, retrieve their current permission entry, modify the role_ids list, and write it back:

Add a role to a user's existing project permission
current = fw.get_project_user_permission(project.id, user_email)
current["role_ids"].append(additional_role_id)
project.update_permission(user_email, current)

Removing a permission

Remove a user from a project
project.delete_permission(user_email)
Remove a user from a group
fw.delete_group_user_permission(group_id, user_email)

Copying permissions across projects

When copying permissions, validate each user before adding: confirm the user account exists on the Flywheel instance and is not already on the destination project. add_permission raises an API error for nonexistent users.

Copy permissions from one project to another
source = fw.get_project(source_project_id)
destination = fw.get_project(destination_project_id)

all_user_ids = {user.id for user in fw.get_all_users()}
existing_user_ids = {perm.id for perm in destination.permissions}

for perm in source.permissions:
    if perm.id not in all_user_ids:
        print(f"Skipping {perm.id}: user does not exist on this instance.")
    elif perm.id in existing_user_ids:
        print(f"Skipping {perm.id}: user is already on the destination project.")
    else:
        destination.add_permission(perm)

Note

This pattern copies permission entries as-is, including role IDs. If the destination project belongs to a different group, ensure the required roles are registered on that group first. See Roles for role management.