User accounts are used to control access to Virtool. They allow fine control of what actions users are allowed to perform and what resources they are allowed to access.



When users create new data items (eg. samples, references, jobs), they are automatically assigned as the owner of that item.

For references and samples, owners have perpetual full rights on their samples and references.


Rights are properties of samples and references that control what actions specific users or user groups are allowed to perform on them.

Administrators automatically pass all rights checks.


Permissions are used to control what application-level actions users are allowed t perform. Permissions are inherited through group membership.

Administrators automatically pass all permission checks.

cancel_jobcan cancel running jobs
create_refcan create references
create_samplecan create samples
modify_hmmcan add and remove HMM annotations and files
modify_subtractioncan add, modify, and remove subtractions
remove_filecan remove uploaded files
remove_jobcan remove cancelled and finished jobs
upload_filecan upload files


Groups allow setting rights and permissions for more than one user. Users that are members of a group will inherit rights and permissions from the group.

It is not possible to set permissions on a per-user basis.


User accounts can either be administrative or limited.

Administrators automatically pass all permission and right checks. They can also access the Administration Panel.

Create a User

  1. Navigate the Users tab under Administration.

    You need to be an administrator to access this view.

    User management toolbar and header

  2. Click to open the user creation dialog.

    Create user dialog

  3. Fill out the user creation form.

    Enter a username and password for the user. Clicking Force user to reset password on login will display a password reset page for the user when they login for the first time.

    Create user dialog with filled form

  4. Click Save

    This will create the new user. The user will appear in the list of users.

    New user added - Bob

Change a User’s Password

Administrators can forcefully change a users’s password. This is useful when a user forgets their password or an old user account must be accessed.

  1. Locate the Change Password panel in the Users tab

    Password panel

  2. Enter a new password

    Password panel with filled form

  3. Click Save

    The Last changed time will be updated if you successfully change the password.

    Password successfully changed

    Clicking Force user to reset password on login will invalidate all of the user’s existing sessions and require them to reset their password when they try to access Virtool.

Change a User’s Group Membership

Users’ group membership can be changed easily.

This may affect what rights the user has on certain samples and references. It can also affect their application permissions.

Locate the Groups panel in the Users tab.

Groups Panel

Click one of the group items to toggle membership in it.

Toggle Group Membership

Notice that the user’s permissions are changed when group membership is toggled.

Change a User’s Primary Group

Samples that a user creates can automatically be assigned to the creating user’s primary user group.

How samples are assigned their initial user group is configurable.

Locate the Primary Group panel under the Users tab.

Primary Group Panel

Select a primary group for the user from the dropdown list of the user’s member groups.

Primary group dropdown

The display group is the user’s primary group.

Primary group changed

Manage Groups

The group management interface can be accessed by clicking to the right of the search bar in Users tab.

Manage groups button

The group management interface looks like this:

Group management interface

Create a Group

Open the group management interface. Enter a name for the new group in the input at the top of dialog and click .

New group input filled

The new group will appear in the groups list.

New group added

Modify a Group’s Permissions

Open the group management interface and select the group you want to change permissions for.

Managers selected in groups interface

Toggle permission by clicking them.

Users added to the Managers group will inherit the toggled permissions.

Remove a Group

Open the group management interface and select the group you want to remove.

Managers selected in groups interface

Click Remove Group to remove the group.

Managers removed