# User Roles and Permissions Guide

_This guide is for IT staff, change management teams, and project administrators who need to manage users, teams, and {{notebooks}} in {{FAIMS}}. It covers role assignment, access control, and common administrative workflows._

---

## Introduction

### Who This Guide Is For

This guide is designed for:

- **Change management staff** onboarding users and managing access
- **Project administrators** setting up teams and {{notebooks}}
- **IT staff** supporting {{FAIMS}} deployments

If you're looking to create {{notebooks}} or collect data, see the [Quickstart Guide](../authoring/quick-start-researchers.md) instead.

### What This Guide Covers (and Doesn't)

This guide covers:

- Managing users at system, team, and {{notebook}} levels
- Role assignment and access control
- Common administrative workflows

This guide does **not** cover:

- Template creation or management
- {{Notebook}} design and form building (see [Quickstart Guide](../authoring/quick-start-researchers.md))
- Data collection and record management
- API access and tokens
- System configuration and Single Sign-On (SSO) setup

### UI Patterns at a Glance

Before diving into procedures, here's how management differs across the three areas:

| Location                  | How to Add User                              | How to Add Role                    | How to Change Role                            | How to Remove                                                                     |
| ------------------------- | -------------------------------------------- | ---------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
| **Users** (system)        | Create a global invite (Users → Invites tab) | Click "add" button in Roles column | Click × on role badge, then add new role      | Click × on role badge (removes role only)                                         |
| **Teams → Users**         | Click "+ Add user" or go to **Invites** tab  | Click "+" on existing member's row | Click × on role badge, then add new role      | Click × on role badge (removes role only), or trash icon (removes user from team) |
| **{{Notebooks}} → Users** | Go to **Invites** tab                        | N/A (one role per user)            | Remove user, then re-invite with desired role | Click trash icon (removes user from {{notebook}})                                 |

### The Three-Tier Permission Model

{{FAIMS}} uses a role-based permissions system to control access to different functions and data. The model centres around access to **resources**: teams, user accounts, templates, {{notebooks}}, and the system as a whole.

Roles are assigned at three levels:

| Level            | Controls                                     |
| ---------------- | -------------------------------------------- |
| **System**       | Global access and creation rights            |
| **Team**         | Access within a team and its resources       |
| **{{Notebook}}** | Access to specific {{notebooks}} and records |

The nearby diagram shows roles at each level and how team roles automatically grant corresponding {{notebook}} access (virtual roles).

```{image} ../images/permissions-hierarchy-v2-3.jpeg
:alt: Permissions Hierarchy Diagram showing System Level (Super User, Operations Administrator, Content Creator, General User), Team Level (Team Administrator, Team Manager, Team Member (Contributor), Team Member (Creator)), and {{Notebook}} Level (Administrator, Manager, Contributor, Guest) with arrows indicating virtual role inheritance from team to {{notebook}} roles. Sidebar shows virtual role inheritance and access sources. Warning callouts highlight that Operations Administrator has no data access and Team Member (Creator) has no automatic access to existing team {{notebooks}}.
```

### What You Can Do As An Enterprise Administrator

As IT or change management staff, you have been provisioned with:

- **Super User** system role — full system control, with inherited Administrator access to all teams and {{notebooks}}

> ⚠️ **Recommendation**: For routine operations (user management, team creation), use the **Operations Administrator** role instead. Super User is an emergency break-glass role that also grants full access to all research data.

This means you can:

**User management:**

- View all system users and their roles
- Add or remove system roles (General User, Content Creator, Operations Administrator, Super User)
- Reset user passwords (for non-SSO configurations)
- Remove user accounts

**Team management:**

- Create new teams
- Access and manage all teams
- Assign Team Administrator roles to others (only Operations Administrator or Super User can do this)

**{{Notebook}} management:**

- Access and manage all {{notebooks}}
- Edit or close any {{notebook}} regardless of ownership

> **Note:** If you cannot perform an action described in this guide, contact your system administrator to verify your role assignments.

### What Operations Administrators Can Do

The **Operations Administrator** role handles routine system management without access to research data:

**User and team management:**

- View all system users and their roles
- Add or remove system roles
- Create new teams
- Assign Team Administrator roles

**Cannot do (by design):**

- Access {{notebooks}}, templates, or research data
- The {{Notebooks}} and Templates sidebar items are hidden from this role

> **Note:** If you need both administrative control and {{notebook}} access, you need the Super User role.

### What Typical Enterprise Users Can Do By Default

During onboarding, enterprise users are typically assigned:

- **Content Creator** system role — they can create {{notebooks}} and templates
- **Team Administrator** of their assigned team — they have full control over their team

These roles are granted through invites created by an Operations Administrator or Super User (see "How Users Are Created" below). Once onboarded, a typical user can immediately:

- Create {{notebooks}} (stand-alone or within their team)
- Invite users to their team and assign team roles
- Invite users to {{notebooks}} they administer and assign {{notebook}} roles
- Manage and update roles for their team members

> **Note:** Users do not have the necessary privileges to create their own teams. Teams are typically created by a Super User or Operations Administrator during onboarding, and users are assigned as Team Administrator of their team via an invite.

### What 'General users' Can Do

The most restricted access level is General User, which can:

- List {{notebooks}} they have access to
- List templates they have access to

General Users have to be granted access to a {{notebook}} directly (via {{notebook}} invite) or through relevant team membership to view or use it.

---

## Navigating the {{Dashboard}}

When you log in to the {{FAIMS}} {{Dashboard}}, you'll see a left sidebar with two sections:

### Content

- **{{Notebooks}}** — View and manage data collection {{notebooks}}
- **Templates** — View and manage reusable {{notebook}} templates

### Management

- **Users** — View all system users and their roles (requires appropriate permissions)
- **Teams** — View and manage teams

```{screenshot} user-roles/01-dashboard-sidebar.png
:alt: {{FAIMS}} {{Dashboard}} showing left sidebar with Content section ({{Notebooks}}, Templates) and Management section (Users, Teams), plus the Users page with Users and Invites tabs, displaying Name, Email, Roles columns with role badges such as General User and Super User
:align: right
:width: 100%
```

> **Tip:** Click on any sidebar item to navigate to that section. The breadcrumb at the top (e.g., "Home > Users") shows your current location.

---

## Managing System Users

The **Users** section shows all users in the system with their email addresses and system-level roles.

### How Users Are Created

In an enterprise deployment, users are created through an invite-based workflow:

1. An Operations Administrator (or Super User) creates an invite — either a global invite for system roles (Users → Invites tab), or a team invite for team roles (Team → Invites tab)
2. The invite is shared with the user via a code, link, or QR code
3. The user accepts the invite and completes sign-in via Single Sign-On (SSO) — this creates their account
4. The user's roles are determined by the invite(s) they accepted, not auto-provisioned

You cannot manually create user accounts through the {{Dashboard}} — users must accept an invite and sign in via SSO to create their account.

> **Note:** SSO auto-provisioning (where user accounts are automatically created on first SSO sign-in with default roles) is under development but not yet deployed. Currently, all user creation requires an invite.

### Viewing Users

1. Click **Users** in the left sidebar (under Management)
2. You'll see a table with columns:
   - **Name** — User's display name
   - **Email** — User's email address
   - **Roles** — System roles with "add" button and role badges
   - **Reset Password** — Not applicable for SSO deployments; password management is handled through your institution's identity provider
   - **Remove** — Remove user from system

The screenshot above shows this view, with the sidebar navigation on the left and the Users table in the main content area.

### Understanding System Roles

There are four system roles: **General User** (basic access), **Content Creator** (can create {{notebooks}} and templates), **Operations Administrator** (manage users and teams without data access), and **Super User** (full system control — emergency use). For detailed permissions, see **Roles Reference → System-Wide Roles** below.

### Adding a Role to a User

1. Find the user in the Users list
2. In the **Roles** column, click the **add** button
3. Select the role to add from the dropdown
4. The new role badge appears next to any existing roles

```{screenshot} user-roles/03-add-user-role.png
:alt: Roles column in Users list showing the add button clicked, revealing a dropdown menu with four role options: General User, Super User, Content Creator, and Operations Administrator
:align: right
:width: 100%
```

### Removing a Role from a User

1. Find the user in the Users list
2. In the **Roles** column, locate the role badge you want to remove
3. Click the **×** in the upper-right corner of the role badge
4. The role is removed immediately

Each role badge (visible in the {{Dashboard}} screenshot earlier) has a small **×** in the upper-right corner — click this to remove the role.

> ⚠️ **Warning**: Be careful when removing roles. If you remove Content Creator from a user, they will no longer be able to create {{notebooks}} globally. However, they can still create {{notebooks}} within teams where they have the Team Member (Creator), Team Manager, or Team Administrator role.

**See also:** Troubleshooting → Can't Assign Team Administrator Role

---

## Managing Global Invites

The **Users** page has two tabs: **Users** (described above) and **Invites**. The Invites tab lets you create invitation links that grant system-level roles to new or existing users — for example, inviting someone to become an Operations Administrator.

> 💡 **Note**: Global invites are for **system-level roles** only. To invite users to a specific team or {{notebook}}, use team invites or {{notebook}} invites instead (see below).

### Who Can Manage Global Invites

Only users with the **Operations Administrator** or **Super User** system role can view and manage global invites.

### Viewing Global Invites

1. Click **Users** in the left sidebar (under Management)
2. Click the **Invites** tab (next to the Users tab)
3. You'll see a table of active invitations with columns:
   - **Name** — Descriptive title for the invitation
   - **Role** — The system role invitees will receive (displayed as a role badge)
   - **Expiry** — When the invitation expires
   - **Uses remaining** — How many more times the invite can be used
   - **Code** — A short code users can enter manually (click to copy)
   - **Link** — A URL users can click to accept the invitation (click to copy)
   - **QR Code** — Click to display a scannable QR code for mobile devices
   - **Remove** — Delete the invitation

```{screenshot} user-roles/02-users-invites-tab.png
:alt: Users page Invites tab showing a table of global invitations with columns for Name, Role, Expiry, Uses remaining, Code, Link, QR Code, and Remove
:align: right
:width: 100%
```

### Creating a Global Invitation

1. Navigate to **Users** → **Invites** tab
2. Click **+ Create Global Invite**
3. Configure the invitation:
   - **Invite title** — A descriptive name (e.g., "Operations team onboarding Q1")
   - **Role** — The system role invitees will receive (General User, Content Creator, or Operations Administrator)
   - **Maximum uses** — How many times the invite can be used (leave empty for unlimited)
   - **Invite Duration** — Choose a preset duration (Quick Select) or a specific date (Custom Date); maximum 365 days
4. Click **Create Invite**

```{screenshot} user-roles/02a-create-global-invite.png
:alt: Create Global Invite dialog with fields for invite title, role selection, maximum uses, and invite duration with Quick Select and Custom Date options
:align: right
:width: 100%
```

> 💡 **Note**: The **Super User** role is deliberately excluded from the role dropdown. Super User access must be granted manually through the Users tab to prevent accidental distribution of full system privileges.

### Removing a Global Invite

To remove an invitation that is no longer needed, click the red **trash icon** in the Remove column of the Invites table. The invite link and code will immediately stop working.

**See also:**

- Managing Teams → Managing Team Invites (similar process for team-level roles)
- Managing {{Notebook}} Users → Inviting Users to a {{Notebook}} (similar process for {{notebook}}-level roles)

---

## Managing Teams

Teams group users together and provide shared access to {{notebooks}}. When you navigate to a team, you'll see several tabs.

### Creating a Team

Only users with the **Super User** or **Operations Administrator** system role can create new teams.

1. Click **Teams** in the left sidebar
2. Click the **+ Create Team** button
3. Enter the team details:
   - **Name** — A descriptive name for the team
   - **Description** — Optional description of the team's purpose
4. Click **Create team**
5. The new team appears in the Teams list

```{screenshot} user-roles/08-teams-create-dialog.png
:alt: Create Team dialog showing Name field and Description field with Create team button
:align: right
:width: 100%
```

After creating a team, you'll typically want to add members and assign a Team Administrator (see "Adding a User to Your Team" below).

> **Note:** Most teams are created during initial provisioning. You'll usually be managing existing teams rather than creating new ones.

### Viewing Your Team

1. Click **Teams** in the left sidebar
2. Click on your team name (teams you administer appear in the expanded sidebar)
3. You'll see tabs: **Details**, **Invites**, **{{Notebooks}}**, **Templates**, **Users**

```{screenshot} user-roles/05-teams-view.png
:alt: Team view for {{FAIMS}} showing the tab bar with Details (selected), Invites, {{Notebooks}}, Templates, and Users tabs, plus the Edit button; main panel displays team name, description, Created By (admin), and timestamps
:align: right
:width: 100%
```

### Team Tabs Overview

| Tab               | Purpose                                 |
| ----------------- | --------------------------------------- |
| **Details**       | Team name and description               |
| **Invites**       | Pending invitations to join the team    |
| **{{Notebooks}}** | {{Notebooks}} associated with this team |
| **Templates**     | Templates owned by this team            |
| **Users**         | Current team members and their roles    |

### Viewing Team Members

1. Navigate to your team
2. Click the **Users** tab
3. You'll see a table with columns:
   - **Name** — Member's display name
   - **Email** — Member's email address
   - **Roles** — Team role badges with **+** to add roles
   - **Remove** — Red trash icon to remove member

```{screenshot} user-roles/06-teams-users.png
:alt: Team Users tab showing member list with columns for Name, Email, Roles (displaying Team Administrator badges with × for removal and + to add roles), and Remove column with red trash icons
:align: right
:width: 100%
```

### Understanding Team Roles

There are four team roles: **Team Administrator** (full control), **Team Manager** (manage members, create {{notebooks}}), **Team Member (Contributor)** (access team resources), and **Team Member (Creator)** (create {{notebooks}} only). Team roles automatically grant corresponding {{notebook}} access — see the permissions diagram in the Introduction or **Roles Reference → Team Roles** below for details.

> ⚠️ **Important**: Team Member (Creator) can create {{notebooks}} but does NOT get automatic access to existing team {{notebooks}}. This role is often used for student or citizen science projects, where it is undesirable for the user to have access to other peoples' {{notebooks}}.

### Adding a User to Your Team

1. Navigate to your team → **Users** tab
2. Click **+ Add user** button above the table
3. Enter the user's email address
4. Select their team role from the dropdown
5. Click **Add User**

```{screenshot} user-roles/07-teams-add-user.png
:alt: Add user to team dialog with User Email text field and Role dropdown showing options: Team Member (Contributor), Team Member (Creator), Team Manager, and Team Administrator
:align: right
:width: 100%
```

### Adding a Role to an Existing Team Member

1. Navigate to your team → **Users** tab
2. Find the member in the list
3. In the **Roles** column, click the **+** button
4. Select the additional role
5. The new role badge appears

### Removing a Role from a Team Member

1. Navigate to your team → **Users** tab
2. Find the member in the list
3. In the **Roles** column, click the **×** on the role badge you want to remove

### Removing a Member from Your Team

1. Navigate to your team → **Users** tab
2. Find the member in the list
3. Click the red **trash icon** in the Remove column
4. Confirm removal when prompted

The screenshot in the "Viewing Team Members" section above shows the red trash icons in the Remove column.

> ⚠️ **Warning**: Removing someone from a team removes their automatic (virtual) access to ALL team {{notebooks}}. If they have direct {{notebook}} roles, that access persists until separately removed.

### Managing Team Invites

The **Invites** tab allows you to create invitation links that users can use to join your team.

#### Creating a Team Invitation

1. Navigate to your team
2. Click the **Invites** tab
3. Click **+ Create Team Invite**
4. Configure the invitation:
   - **Invite title** — A descriptive name for the invitation
   - **Role** — The team role new members will receive
   - **Uses** — How many times the invite can be used (leave empty for unlimited)
   - **Expiry** — When the invitation expires (see below)
5. Click **Create Invite**

```{screenshot} user-roles/08b-teams-create-invite.png
:alt: Create Team Invite dialog showing Role dropdown with team roles, Expiry date field, and Create Invite button
:align: right
:width: 100%
```

#### Understanding Invite Options

| Option             | Description                                                                                                                                          |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Expiry**         | The date/time after which the invite link no longer works. Expired invites cannot be extended — create a new one instead.                            |
| **Uses remaining** | Limits how many people can use this invite. Use multi-use invites for workshops or group onboarding. Leave unlimited (default) for open invitations. |
| **Code**           | A short code users can enter manually                                                                                                                |
| **Link**           | A URL that users can click to accept the invitation                                                                                                  |
| **QR Code**        | Scannable code for mobile devices — useful for in-person onboarding                                                                                  |

#### Viewing and Managing Invites

The Invites tab shows all active invitations with their status.

```{screenshot} user-roles/08a-teams-invites-tab.png
:alt: Team Invites tab showing list of pending invitations with columns for Name, Role, Expiry, Uses remaining, Code, Link, QR Code, and Remove
:align: right
:width: 100%
```

From here you can:

- See how many uses remain on each invite
- Check expiry dates
- Remove invites that are no longer needed (click the trash icon)

**See also:**

- Managing {{Notebook}} Users → Inviting Users to a {{Notebook}} (similar process)
- Troubleshooting → Can't Add Users to Team
- Troubleshooting → User Has Access But Shouldn't

---

## Managing {{Notebook}} Users

{{Notebooks}} have their own user management, separate from teams. Users can access {{notebooks}} either through team membership (virtual roles) or direct assignment.

### Viewing {{Notebook}} Users

1. Click **{{Notebooks}}** in the left sidebar

```{screenshot} user-roles/09a-notebooks-view.png
:alt: {{Notebooks}} list view showing sidebar with {{Notebooks}} expanded, and main content area with table columns for Name, Team, Template, {{Notebook}} Lead, and Description
:align: right
:width: 100%
```

2. Click on a {{notebook}} name
3. Click the **Users** tab
4. You'll see a table with columns:
   - **Name** — User's display name
   - **{{Notebook}} Roles** — Current role (display only)
   - **Remove** — Trash icon to remove user

```{screenshot} user-roles/09b-notebooks-users.png
:alt: {{Notebook}} Users tab showing user list with Name column, {{Notebook}} Roles column (displaying Administrator badges), and Remove column with trash icons
:align: right
:width: 100%
```

### {{Notebook}} Tabs Overview

| Tab         | Purpose                                                                       |
| ----------- | ----------------------------------------------------------------------------- |
| **Details** | {{Notebook}} name, description, and metadata                                  |
| **Invites** | Invitation links for adding users                                             |
| **Users**   | Current {{notebook}} users and their roles                                    |
| **Export**  | Export {{notebook}} data                                                      |
| **Actions** | Edit {{notebook}}, assign to team, download/replace JSON, {{notebook}} status |

### Understanding {{Notebook}} Roles

There are four {{notebook}} roles: **Administrator** (full control, can manage administrators), **Manager** (edit design, export, manage access), **Contributor** (edit others' records), and **Guest** (own records only). For detailed permissions, see **Roles Reference → {{Notebook}} Roles** and the **Permission Matrix** below.

### How {{Notebook}} Access Works

Users can have {{notebook}} access from two sources:

1. **Virtual roles** — Automatic access from team membership (see the permissions diagram in the Introduction for the mapping)
2. **Direct roles** — Explicitly assigned to this {{notebook}} via invitation

> **Note:** Direct roles override virtual roles. If a Team Member (Contributor) is directly assigned as Guest on a specific {{notebook}}, they have Guest access to that {{notebook}}.

### Inviting Users to a {{Notebook}}

Unlike Teams, you **cannot add users directly** to a {{notebook}}. Instead, you create invitation links that users can accept to join with a specific role.

1. Navigate to your {{notebook}}
2. Click the **Invites** tab
3. Click **+ Create Invite**
4. Configure the invitation:
   - **Invite title** — A descriptive name for the invitation (e.g., "Field team contributor access")
   - **Role** — The {{notebook}} role recipients will receive (Administrator, Manager, Contributor, or Guest)
   - **Uses** — How many times the invite can be used (leave empty for unlimited)
   - **Expiry** — When the invitation expires
5. Click **Create Invite**

```{screenshot} user-roles/10-notebooks-invite.png
:alt: Create Invite dialog for a {{notebook}} showing Invite title field, Role dropdown with options (Administrator, Manager, Contributor, Guest), expiry date selection with Quick Select and Custom Date options, and Create Invite button
:align: right
:width: 100%
```

Once created, invitations appear in the **Invites** tab where you can manage them:

```{screenshot} user-roles/11-notebooks-invites-active.png
:alt: {{Notebook}} Invites tab showing list of active invitations with columns for Name, Role, Expiry, Uses remaining, Code, Link, QR Code, and Remove; includes + Create Invite button
:align: right
:width: 100%
```

The Invites tab shows:

| Column             | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| **Name**           | The invitation title/description                             |
| **Role**           | The {{notebook}} role recipients will receive                |
| **Expiry**         | When the invite expires — create a new invite if one expires |
| **Uses remaining** | How many more people can use this invite                     |
| **Code**           | Short code for manual entry                                  |
| **Link**           | Clickable URL to share                                       |
| **QR Code**        | Scannable code for mobile onboarding                         |

> **Tip:** Use multi-use invites with QR codes for field team onboarding sessions. Each team member can scan the same code to join with the appropriate role.

### Removing a User from a {{Notebook}}

1. Navigate to the {{notebook}} → **Users** tab
2. Find the user in the list
3. Click the **trash icon** in the Remove column
4. Confirm removal

> **Note:** Removing a direct role doesn't remove team membership. If the user has a team role, they'll still have virtual access through the team.

### Transferring {{Notebook}} Ownership

To hand off a {{notebook}} to someone else:

1. Go to the {{notebook}} → **Invites** tab
2. Invite the new owner with **Administrator** role
3. Once they accept, they have full control
4. Optionally remove yourself via the **Users** tab

> ⚠️ **Warning**: Always ensure at least one Administrator remains on every {{notebook}}.

**See also:**

- Troubleshooting → Can't See a {{Notebook}}
- Troubleshooting → Can't Change a User's {{Notebook}} Role

---

## Quick Reference

### When to Use Each Role

| Scenario                                                         | Recommended Role                                      |
| ---------------------------------------------------------------- | ----------------------------------------------------- |
| Project lead who manages everything                              | Team Administrator + {{notebook}} Administrator       |
| Researcher who designs forms                                     | Team Manager or {{notebook}} Manager                  |
| Field worker collecting data                                     | Team Member (Contributor) or {{notebook}} Contributor |
| External reviewer (limited access)                               | {{Notebook}} Guest                                    |
| Someone who creates {{notebooks}} but shouldn't see others' data | Team Member (Creator)                                 |

---

## Common Scenarios

### Onboarding a New Researcher (Typical Pathway)

1. An Operations Administrator creates a new team for the researcher (Teams → **+ Create Team**)
2. Create a Team Administrator invite for the new team (Team → **Invites** tab → **+ Create Team Invite**, selecting **Team Administrator** role)
3. Send the invite link (or code/QR code) to the researcher
4. The researcher accepts the invite and signs in via SSO — this creates their account with the Team Administrator role
5. Optionally, add the **Content Creator** system role (Users → find user → **add** button in Roles column) so they can create {{notebooks}} outside their team

### Adding an Existing User to Your Team

1. Navigate to your team → **Users** tab → **+ Add user**
2. Enter their email and select the appropriate team role (e.g., **Team Member (Contributor)**)
3. They now have the corresponding virtual access to all your team's {{notebooks}}

Alternatively, create a team invite (Team → **Invites** tab → **+ Create Team Invite**) and share it with the user.

### Setting Up a Project Team

1. Create {{notebook}}(s) for the project ({{Notebooks}} → Create {{Notebook}})
2. Ensure {{notebooks}} are associated with your team
3. Add team members with appropriate roles:
   - Project lead: Team Manager or Team Administrator
   - Researchers: Team Member (Contributor)
   - External collaborators: Invite directly to specific {{notebooks}}

### Granting External Collaborator Access

**Option A — Add to team** (ongoing access):

1. Add them to your team as Team Member (Contributor)
2. They get virtual access to all team {{notebooks}}

**Option B — {{Notebook}} only** (limited scope):

1. Go to the specific {{notebook}} → **Invites** tab
2. Invite them with Contributor or Guest role
3. They don't need team membership

### Handing Off a Project

1. {{Notebook}} → **Invites** tab → Invite colleague as **Administrator**
2. Verify they can access and manage the {{notebook}}
3. Optionally remove yourself from the Users tab

### Off-boarding: Removing All Access

1. **Remove from {{notebooks}}** (if they have direct roles):
   - Navigate to each {{notebook}} → Users tab → trash icon
2. **Remove from team**:
   - Navigate to team → Users tab → red trash icon
3. **Note**: You cannot revoke system roles — contact a system administrator (Super User or Operations Administrator)

---

## Roles Reference

### System-Wide Roles

| Role                     | Description                                                 | Typical User                  |
| ------------------------ | ----------------------------------------------------------- | ----------------------------- |
| General User             | View assigned resources, manage own tokens                  | Rarely used alone             |
| Content Creator          | Create {{notebooks}} and templates globally                 | Researchers, project managers |
| Operations Administrator | Manage users, teams, and system operations (no data access) | IT operations staff           |
| Super User               | Full system control, all data access (emergency use)        | IT administrators             |

### Team Roles

| Role                      | Permissions                          | Virtual {{Notebook}} Role                        |
| ------------------------- | ------------------------------------ | ------------------------------------------------ |
| Team Administrator        | Full team control                    | Administrator                                    |
| Team Manager              | Manage members, create {{notebooks}} | Manager                                          |
| Team Member (Contributor) | Access team resources                | Contributor                                      |
| Team Member (Creator)     | Create {{notebooks}} only            | **None** (no access to other team {{notebooks}}) |

> ⚠️ **Key restriction**: Only Operations Administrator or Super User can assign Team Administrator role. Team Member (Creator) cannot see other team {{notebooks}} — they must be explicitly invited.

### {{Notebook}} Roles

| Role                | Permissions                                                         |
| ------------------- | ------------------------------------------------------------------- |
| Project Admin       | Full control, manage administrators                                 |
| Project Manager     | Edit design, close {{notebook}}, export, manage invites/access      |
| Project Contributor | Edit others' records (plus all Guest permissions)                   |
| Project Guest       | Activate {{notebook}}, create records, view/edit/delete own records |

### Permission Matrix — {{Notebooks}}

| Action                       | Guest | Contributor | Manager | Administrator |
| ---------------------------- | :---: | :---------: | :-----: | :-----------: |
| Create records               |  ✅   |     ✅      |   ✅    |      ✅       |
| View/edit/delete own records |  ✅   |     ✅      |   ✅    |      ✅       |
| View all records             |  ❌   |     ✅      |   ✅    |      ✅       |
| Edit/delete others' records  |  ❌   |     ✅      |   ✅    |      ✅       |
| Export own data              |  ✅   |     ✅      |   ✅    |      ✅       |
| Export all {{notebook}} data |  ❌   |     ❌      |   ✅    |      ✅       |
| Edit {{notebook}} design     |  ❌   |     ❌      |   ✅    |      ✅       |
| Close/reopen {{notebook}}    |  ❌   |     ❌      |   ✅    |      ✅       |
| Reassign to different team   |  ❌   |     ❌      |   ✅    |      ✅       |
| Manage invites and users     |  ❌   |     ❌      |   ✅    |      ✅       |
| Manage administrators        |  ❌   |     ❌      |   ❌    |      ✅       |

### Permission Matrix — Teams

| Action                                   | Member | Member Creator | Manager |                    Admin                    |
| ---------------------------------------- | :----: | :------------: | :-----: | :-----------------------------------------: |
| View team details and members            |   ✅   |       ✅       |   ✅    |                     ✅                      |
| View team templates                      |   ✅   |       ❌       |   ✅    |                     ✅                      |
| Access team {{notebooks}} (virtual role) |   ✅   |       ❌       |   ✅    |                     ✅                      |
| Create {{notebooks}} in team             |   ❌   |       ✅       |   ✅    |                     ✅                      |
| Create templates in team                 |   ❌   |       ❌       |   ✅    |                     ✅                      |
| Edit team details                        |   ❌   |       ❌       |   ✅    |                     ✅                      |
| Add/remove team members                  |   ❌   |       ❌       |   ✅    |                     ✅                      |
| Manage team invites                      |   ❌   |       ❌       |   ✅    |                     ✅                      |
| Add/remove team managers                 |   ❌   |       ❌       |   ❌    |                     ✅                      |
| Add team admins                          |   ❌   |       ❌       |   ❌    | Operations Administrator or Super User only |
| Delete team                              |   ❌   |       ❌       |   ❌    |                     ✅                      |

> ⚠️ **Note**: Team Member (Creator) can create {{notebooks}} but does NOT automatically get access to existing team {{notebooks}}. This is by design for teaching environments where students create isolated {{notebooks}}.
>
> Virtual roles: Team Member (Contributor) automatically receives **Contributor** access to team {{notebooks}}. Team Manager automatically receives **Manager** access. Team Administrator inherits Manager's virtual role. Team Member (Creator) receives **no** virtual {{notebook}} access.

---

## Troubleshooting

### Can't See a {{Notebook}}

**Possible causes**:

- Not a member of the team that owns the {{notebook}}
- Team role is Team Member (Creator) — doesn't grant automatic access
- Not directly invited to the {{notebook}}

**Solution**: Check team membership and role. Add direct {{notebook}} access via Invites tab if needed.

### Can't Edit {{Notebook}} Structure

**Cause**: Missing Manager or Administrator role on the {{notebook}}.

**Solution**: Have a {{notebook}} Administrator invite you with Manager or Administrator role.

### Can't Add Users to Team

**Cause**: Missing Team Manager or Team Administrator role.

**Solution**: Have a Team Administrator elevate your team role.

### Can't Assign Team Administrator Role

**Cause**: Only Operations Administrator or Super User can assign Team Administrator roles.

**Solution**: Contact an Operations Administrator or Super User to assign the Team Administrator role.

### User Has Access But Shouldn't

**Cause**: User may have both direct and virtual (team-based) roles.

**Solution**: Check both:

1. Direct {{notebook}} roles ({{Notebook}} → Users tab)
2. Team membership (Team → Users tab)

Remove from both locations if needed.

### Can't Change a User's {{Notebook}} Role

**Note**: The {{Notebook}} Users tab only displays roles — you cannot edit them there.

**Solution**: Remove the user (trash icon), then re-invite via the **Invites** tab with the new role.

---

## Further Resources

- [Quickstart Guide](../authoring/quick-start-researchers.md) — Creating {{notebooks}} and collecting data

---

_Guide Version: 1.8_
_Last Updated: 2026-02-24_