Users

List users

Get a list of users.

GET /api/v1/users/{?page,limit,filter,sort}

URL Parameters

Name Description
page integer (optional) See Paging
limit integer (optional) See Paging
detailed boolean (optional) See Summary / Detailed Representations
filter string (optional) See Filtering
sort string (optional) See Sorting

Response 200 OK

{
    "timestamp": "2016-04-15T11:30:24.510187039-04:00",
    "data": [
        {
            "id": "1",
            "admin": true,
            "disabled": false,
            "name": "admin",
            "description": "",
            "locked": false
        },
        {
            "id": "3",
            "admin": true,
            "disabled": false,
            "name": "admin2",
            "description": "",
            "locked": false
        },
        {
            "id": "309",
            "admin": false,
            "disabled": false,
            "name": "john",
            "description": "",
            "locked": false
        },
        {
            "id": "307",
            "admin": false,
            "disabled": false,
            "name": "smith",
            "description": "",
            "locked": false
        }
    ],
    "links": {
        "current": 1,
        "first": 1,
        "last": 1,
        "limit": 10,
        "total": 4
    }
}

Get a user

Get a user.

GET /api/v1/users/{id}/

Response 200 OK

{
    "timestamp": "2016-04-15T11:32:16.252824617-04:00",
    "data": {
        "id": "1",
        "admin": true,
        "disabled": false,
        "name": "admin",
        "description": "",
        "created": "2016-01-25T11:51:05.79363-05:00",
        "updated": "2016-04-12T14:28:15.479142-04:00",
        "locked": false,
        "token": "66963dc0"
    }
}

Response 404 Not Found

{
    "error": "no such user"
}

Create a user

Create a new user.

POST /api/v1/users/

Example

Fields password and password_confirm must be equal.

{
    "admin": false,
    "disabled": false,
    "name": "newuser",
    "description": "my new user",
    "password": "123",
    "password_confirm": "123"
}

Response 200 OK

{
    "timestamp": "2016-04-15T11:38:47.449193869-04:00",
    "data": {
        "id": "310",
        "admin": false,
        "disabled": false,
        "name": "newuser",
        "description": "my new user",
        "created": "2016-04-15T11:38:47.403281794-04:00",
        "updated": "2016-04-15T11:38:47.403281794-04:00",
        "locked": false,
        "token": "0ea01300"
    }
}

Edit a user

Edit a user.

PATCH /api/v1/users/{id}/

Example

PATCH /api/v1/users/123/

{
    "admin": false,
    "disabled": false,
    "name": "olduser",
    "description": "my old user",
}

Response 200 OK

{
    "timestamp": "2016-04-15T11:39:31.64825128-04:00",
    "data": {
        "id": "123",
        "admin": false,
        "disabled": false,
        "name": "olduser",
        "description": "my old user",
        "created": "2016-04-15T11:38:47.403282-04:00",
        "updated": "2016-04-15T11:39:31.620624675-04:00",
        "locked": false,
        "token": "0ea01300"
    }
}

Change a user’s password

Change a user’s password.

POST /api/v1/users/{id}/password{?change_token}

URL Parameters

Name Description
change_token boolean (optional) If false, don’t generate new API token. Default: true

Example

The field old can be omitted if you are an admin user. The fields new and new_confirm must be equal.

POST /api/v1/users/123/password

{
    "old": "old-password",
    "new": "new-password",
    "new_confirm": "new-password"
}

Response 200 OK

{
    "timestamp": "2016-04-15T11:27:14.220668762-04:00",
    "data": {
        "id": "123",
        "admin": false,
        "disabled": false,
        "name": "john",
        "description": "John's user",
        "created": "2016-03-31T11:47:15.345494-04:00",
        "updated": "2016-04-15T11:27:14.20463507-04:00",
        "locked": false,
        "token": "395771cc"
    }
}

Change a user’s token

Change a user’s token.

POST /api/v1/users/{id}/token

Response 200 OK

{
    "timestamp": "2016-04-15T11:40:51.854710988-04:00",
    "data": {
        "id": "123",
        "admin": false,
        "disabled": false,
        "name": "olduser",
        "description": "my old user",
        "created": "2016-04-15T11:38:47.403282-04:00",
        "updated": "2016-04-15T11:40:51.837981458-04:00",
        "locked": false,
        "token": "099d94b2"
    }
}

Delete a user

Delete a user.

DELETE /api/v1/users/{id}/

Response 204 No Content

Lock a user

Lock a user. Locking a user prevents it from being modified or deleted until it is unlocked.

POST /api/v1/users/{id}/lock

Response 200 OK

{
  "timestamp": "2023-03-29T15:35:48.434137902-04:00",
  "data": {
    "id": "3",
    "admin": true,
    "disabled": false,
    "name": "admin2",
    "description": "",
    "created": "2022-11-04T14:19:19.842488-04:00",
    "updated": "2023-03-29T15:35:48.429815952-04:00",
    "locked": true,
    "token": "75d6517c"
  }
}

Unlock a user

Unlock a user. Unlocking a locked user allows it to be modified or deleted once again.

POST /api/v1/users/{id}/unlock

Response 200 OK

{
  "timestamp": "2023-03-29T15:35:48.434137902-04:00",
  "data": {
    "id": "3",
    "admin": true,
    "disabled": false,
    "name": "admin2",
    "description": "",
    "created": "2022-11-04T14:19:19.842488-04:00",
    "updated": "2023-03-29T15:35:48.429815952-04:00",
    "locked": false,
    "token": "75d6517c"
  }
}

Bulk copy users

Bulk copy a set of users.

POST /api/v1/users/?bulk=copy

Example

POST /api/v1/users/?bulk=copy

{
    "users": [
        {"id": "1"},
        {"id": "3"}
    ]
}

Response 200 OK

Returns users array containing new users copied from input IDs.

{
    "timestamp": "2016-04-15T11:55:18.751101038-04:00",
    "data": [
        {
            "id": "313",
            "admin": true,
            "disabled": false,
            "name": "admin (copy 1)",
            "description": "",
            "created": "2016-04-15T11:55:18.731537576-04:00",
            "updated": "2016-04-15T11:55:18.731537576-04:00",
            "locked": false,
            "token": "1aed4342"
        },
        {
            "id": "314",
            "admin": true,
            "disabled": false,
            "name": "admin2 (copy 1)",
            "description": "",
            "created": "2016-04-15T11:55:18.733389992-04:00",
            "updated": "2016-04-15T11:55:18.733389992-04:00",
            "locked": false,
            "token": "44fbbd92"
        }
    ]
}

Bulk edit users

Bulk edit a set of users.

POST /api/v1/users/{?bulk=edit,filter,all}

URL Parameters

Name Description
bulk string (required) Must be edit
filter string (optional) See Filtering
all boolean (optional) If true, apply edits to all users.

Example

Bulk edit users 5 and 286, setting their description field to Managers.

POST /api/v1/users/?bulk=edit

{
    "users": [
        {"id": "5"},
        {"id": "286"}
    ],
    "fields": {
        "description": "Managers"
    }
}

Bulk edit users matching filters id>10 and description=Managers, setting their description field to Bar.

POST /api/v1/users/?bulk=edit&filter=id>10&filter=description=Managers

{
    "fields": {
        "description": "Bar"
    }
}

Bulk edit all users, setting their description field to Foo.

POST /api/v1/users/?bulk=edit&all=true

{
    "fields": {
        "description": "Foo"
    }
}

Response 204 No Content

Bulk delete users

Bulk delete a set of users.

POST /api/v1/users/{?bulk=delete,filter,all}

URL Parameters

Name Description
bulk string (required) Must be delete
filter string (optional) See Filtering
all boolean (optional) If true, delete all users.

Example

Bulk delete users 5 and 286.

POST /api/v1/users/?bulk=delete

{
    "users": [
        {"id": "5"},
        {"id": "286"}
    ]
}

Bulk delete users matching filters id>3 and description=Managers.

POST /api/v1/users/?bulk=delete&filter=id>10&filter=description=Managers

Bulk delete all users.

POST /api/v1/users/?bulk=delete&all=true

Response 204 No Content