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
--8 < --"test_docs_admin_concepts.py:read_project_permissions"
Read permissions on a group
--8 < --"test_docs_admin_concepts.py:read_group_permissions"

Adding a permission

Add a user to a project
--8 < --"test_docs_admin_concepts.py:add_project_permission"
Add a user to a group
--8 < --"test_docs_admin_concepts.py:add_group_permission"

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
--8 < --"test_docs_admin_concepts.py:update_project_permission"

Removing a permission

Remove a user from a project
--8 < --"test_docs_admin_concepts.py:delete_project_permission"
Remove a user from a group
--8 < --"test_docs_admin_concepts.py:delete_group_permission"

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
--8 < --"test_docs_admin_concepts.py:copy_project_permissions"

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.