users

Find users

Find all Virtool users.

The active query parameter can be used to filter users by their active status.

The find query parameter can be used to filter users by partial matches to their handles.

Request

get
/users

Response

{
  "status": "200"
}

Create a user

Creates a new user.

Parameters

Name Type Required Description
force_reset boolean false forces a password reset next time the user logs in
handle string true the unique handle for the user
password string true the password for the user

Errors

StatusDescription
400 Password does not meet length requirement
403 Not permitted

Request

post
/users

Response

{
  "status": "201"
}

Create a first user

Creates the first user for the instance. This endpoint will not succeed more than once.

After calling this endpoint, authenticate as the first user and use those credentials to continue interacting with the API.

Parameters

Name Type Required Description
handle string true the unique handle for the user
password string true the password for the user

Errors

StatusDescription
400 Bad request
403 Not permitted

Request

put
/users/first

Response

{
  "status": "201"
}

Retrieve a user

Fetches the details for a user.

Errors

StatusDescription
403 Not permitted
404 Not found

Request

get
/users/{user_id}

Response

{
  "status": "200"
}

Update a user

Updates and existing user with the provided parameters. Users cannot modify their own administrative status.

Parameters

Name Type Required Description
active boolean false make a user active or not
force_reset boolean false forces a password reset next time the user logs in
groups array false sets the IDs of groups the user belongs to
password string false the new password
primary_group integer false set the ID of the user's primary group

Errors

StatusDescription
400 Bad request
403 Not permitted
404 Not found
409 User is not member of group

Request

patch
/users/{user_id}

Response

{
  "status": "200"
}

List user roles

Lists all roles that a user has on the space.

Request

get
/users/{user_id}/permissions

Response

{
  "example": [
    "create_ref",
    "create_sample"
  ],
  "status": "200"
}

Delete user permission

Removes a permission for a user.

Request

delete
/users/{user_id}/permissions/{role}

Response

{
  "example": true,
  "status": "200"
}

Add user role

Adds a role for a user.

Request

put
/users/{user_id}/permissions/{role}

Response

{
  "example": true,
  "status": "200"
}