Legacy API Docs. These docs are for Virtool 4.4.0.

Users

List

Requires manage_users permission

Get a list of complete representations of all users.

GET
/api/users

Example

GET /api/users

Response

Status: 200 OK

[
  {
    "groups": ["administrator"],
    "permissions": {
      "cancel_job": true,
      "create_sample": true,
      "modify_hmm": true,
      "modify_subtraction": true,
      "rebuild_index": true,
      "remove_file": true,
      "remove_job": true,
      "upload_file": true
    },
    "primary_group": "",
    "force_reset": false,
    "last_password_change": "2018-02-06T17:25:14.867000Z",
    "identicon": "6be6d0a72a16cb633144ec03cdaef77804c6f94770184f83e0899fe6bdcb77ee",
    "id": "igboyes"
  },
  {
    "groups": [],
    "identicon": "d0cfc2e5319b82cdc71a33873e826c93d7ee11363f8ac91c4fa3a2cfcd2286e5",
    "permissions": {
      "cancel_job": false,
      "create_sample": false,
      "manage_users": false,
      "modify_hmm": false,
      "modify_settings": false,
      "modify_subtraction": false,
      "modify_virus": false,
      "rebuild_index": false,
      "remove_file": false,
      "remove_job": false,
      "remove_virus": false,
      "upload_file": false
    },
    "primary_group": "",
    "force_reset": false,
    "last_password_change": "2018-02-07T17:56:35.980000Z",
    "id": "fred"
  }
]

Errors

StatusMessageReason
403Not permittedclient does not have the ‘manage_users` permission

Get

Role Administrator

Get the complete representation of a single user.

GET
/api/users/:id

Example

GET /api/users/fred

Response

Status: 200 OK

{
  "groups": [],
  "identicon": "d0cfc2e5319b82cdc71a33873e826c93d7ee11363f8ac91c4fa3a2cfcd2286e5",
  "permissions": {
    "cancel_job": false,
    "create_sample": false,
    "manage_users": false,
    "modify_hmm": false,
    "modify_settings": false,
    "modify_subtraction": false,
    "modify_virus": false,
    "rebuild_index": false,
    "remove_file": false,
    "remove_job": false,
    "remove_virus": false,
    "upload_file": false
  },
  "primary_group": "",
  "force_reset": false,
  "last_password_change": "2018-02-07T17:56:35.980000Z",
  "id": "fred"
}

Errors

StatusMessageReason
403Not permittedclient is not an administrator
404Not founduser does not exist

Create

Role Administrator

Create a new user.

POST
/api/users

Input

NameTypeRequiredDescription
user_idStringTruethe desired username
passwordStringTruethe desired password
force_resetStringFalseforce password reset on login (default=true)

Example

POST /api/users

{
  "user_id": "bill",
  "password": "foobar"
}

Response

Status: 201 Created

{
  "force_reset": true,
  "groups": [],
  "identicon": "623210167553939c87ed8c5f2bfe0b3e0684e12c3a3dd2513613c4e67263b5a1",
  "last_password_change": "2018-02-07T17:59:10.572000Z",
  "permissions": {
    "cancel_job": false,
    "create_sample": false,
    "manage_users": false,
    "modify_hmm": false,
    "modify_settings": false,
    "modify_subtraction": false,
    "modify_virus": false,
    "rebuild_index": false,
    "remove_file": false,
    "remove_job": false,
    "remove_virus": false,
    "upload_file": false
  },
  "primary_group": "",
  "id": "bill"
}

Errors

StatusMessageReason
400Password does not meet length requirementpassword must meet minimum_password_length setting
400User already existsuser_id is already in use
403Not permittedclient is not an administrator
422Invalid inputJSON request body is invalid

Edit

Role Administrator

Change the password, primary group, or force reset setting of an existing user.

Adminstrators cannot modify their own administrative status.

PATCH
/api/users/:id

Input

NameTypeDescription
administratorbooleanset the user’s adminstrator status
force_resetbooleanforce a password reset next time the user logs in
passwordstringthe new password
primary_groupstringthe users primary group used for sample rights
groupsarraythe ids of the groups the user belongs to

Example

PATCH /api/users/fred

{
  "force_reset": true,
  "password": "foobar"
}

Response

Status: 200 OK

{
  "groups": [],
  "identicon": "d0cfc2e5319b82cdc71a33873e826c93d7ee11363f8ac91c4fa3a2cfcd2286e5",
  "permissions": {
    "cancel_job": false,
    "create_sample": false,
    "manage_users": false,
    "modify_hmm": false,
    "modify_settings": false,
    "modify_subtraction": false,
    "modify_virus": false,
    "rebuild_index": false,
    "remove_file": false,
    "remove_job": false,
    "remove_virus": false,
    "upload_file": false
  },
  "primary_group": "none",
  "force_reset": true,
  "last_password_change": "2018-02-07T18:22:14.219000Z",
  "id": "fred"
}

Errors

StatusMessageReason
400Groups do not existone or more passed groups do not exist
400Primary group does not existpassed primary_group does not exist
400Password does not meet length requirementpassword must meet minimum_password_length setting
400Users cannot modify their own administrative statusanother administrator should perform the action
403Not permittedclient is not an administrator
404Not founduser does not exist
409User is not member of groupuser is not a member of the passed primary_group
422Invalid inputJSON request body is invalid

Remove

Role Administrator

Remove a user account.

DELETE
/api/users/:id

Example

DELETE /api/users/bill

Response

Status: 204 No content

 

Errors

StatusMessageReason
400Cannot remove own accountusers cannot remove their own accounts
403Not permittedclient is not an administrator
404Not founduser does not exist