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
Status | Message | Reason |
---|---|---|
403 | Not permitted | client 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
Status | Message | Reason |
---|---|---|
403 | Not permitted | client is not an administrator |
404 | Not found | user does not exist |
Create
Role Administrator
Create a new user.
POST
/api/users
Input
Name | Type | Required | Description |
---|---|---|---|
user_id | String | True | the desired username |
password | String | True | the desired password |
force_reset | String | False | force 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
Status | Message | Reason |
---|---|---|
400 | Password does not meet length requirement | password must meet minimum_password_length setting |
400 | User already exists | user_id is already in use |
403 | Not permitted | client is not an administrator |
422 | Invalid input | JSON 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
Name | Type | Description |
---|---|---|
administrator | boolean | set the user’s adminstrator status |
force_reset | boolean | force a password reset next time the user logs in |
password | string | the new password |
primary_group | string | the users primary group used for sample rights |
groups | array | the 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
Status | Message | Reason |
---|---|---|
400 | Groups do not exist | one or more passed groups do not exist |
400 | Primary group does not exist | passed primary_group does not exist |
400 | Password does not meet length requirement | password must meet minimum_password_length setting |
400 | Users cannot modify their own administrative status | another administrator should perform the action |
403 | Not permitted | client is not an administrator |
404 | Not found | user does not exist |
409 | User is not member of group | user is not a member of the passed primary_group |
422 | Invalid input | JSON 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
Status | Message | Reason |
---|---|---|
400 | Cannot remove own account | users cannot remove their own accounts |
403 | Not permitted | client is not an administrator |
404 | Not found | user does not exist |