API v2: Users

API v2

Sections: List users | Show a user | Create a user | Update a user | Change the password of a user | Activate/deactivate a user | Convert a normal (not LDAP) user to LDAP user| Convert an LDAP user to normal | Delete a user

List users

Returns all the users in Team Password Manager:

GET /users.json

The response from these request is paginated and /count.json and /page/num.json can be used. See the section on pagination for more information. Example: GET /users/page/2.json

If successful, the response code is 200 OK with the results of the call in the response body.

*Note: users with "Normal user" and "Project Manager" roles can also execute this request, getting only the id and name for each user. Users with "Read only" role can't.

Example response body (executed by users with "Admin" or "IT" roles):

[
  {
    "id": 18,
    "name": "Alan Hall",
    "username": "alan",
    "email_address": "Alan.Hall@teampasswordmanager.com",
    "role": "Normal user",
    "is_active": true,
    "is_ldap": true,
    "is_2fa_enabled": false,
    "valid_hash": true,
    "num_groups": 1
  },
  {
    "id": 3,
    "name": "Claire Wood",
    "username": "claire",
    "email_address": "claire@teampasswordmanager.com",
    "role": "Project manager",
    "is_active": true,
    "is_ldap": false,
    "is_2fa_enabled": false,
    "valid_hash": true,
    "num_groups": 1
  },
...
]

Show a user

This method returns all the data of a user, identified by its internal id.

GET /users/ID.json

If successful, the response code is 200 OK with the results of the call in the response body.

Example response body:

{
  "id": 1,
  "username": "john",
  "email_address": "john@teampasswordmanager.com",
  "name": "John Boss",
  "role": "Admin",
  "is_active": true,
  "is_ldap": false,
  "login_dn": "",
  "is_2fa_enabled": false,
  "valid_hash": true,
  "groups": [
    {
      "id": 2,
      "name": "IT works"
    },
    {
      "id": 1,
      "name": "Web work"
    }
  ],
  "last_login": "2014-07-23 18:17:10",
  "last_api_request": "2014-07-23 23:18:15",
  "created_on": "2014-06-05 16:35:13",
  "created_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  },
  "updated_on": "2014-07-23 23:20:55",
  "updated_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  }
}

Create a user

POST /users.json

The request body must include the data for the user:

{
  "username": "johnnotboss",
  "email_address": "john@test.com",
  "name": "John",
  "role": "normal user",
  "password": "testpassword"
}

If successful, the response code is 201 Created with the internal id of the user in the response body:

{
  "id": 15
}

The following fields MUST be used when creating a user: 'username', 'email_address', 'name' and 'role' (case insensitive: 'admin', 'project manager', 'normal user', 'read only' or 'only read', 'it').

One of these two fields MUST be used when creating a user:

• 'password': if this field is set, the user will be a normal (not LDAP) user.
• 'login_dn': if this field is set, the user will be an LDAP user (if LDAP is enabled).

Update a user

PUT /users/ID.json

The request body must include the data for the user. Only the fields that are included are updated, the other fields are left unchanged:

{
  "name": "Johnny"
}

If successful, the response code is 204 No content and the response body is empty.

The following fields can be used when updating a user: 'username', 'email_address', 'name', 'role' (case insensitive: 'admin', 'project manager', 'normal user', 'read only' or 'only read', 'it') and 'login_dn' (if the user is an LDAP user).

* Note: the password of the user cannot be set by updating the user. There's a request for this:

Change the password of a user

PUT /users/ID/change_password.json

The request body must include the new password for the user:

{
  "password": "thisistheone"
}

If successful, the response code is 204 No content and the response body is empty.

Activate/deactivate a user

PUT /users/ID/activate.json

PUT /users/ID/deactivate.json

If successful, the response code is 204 No content and the response body is empty.

* Note: a user cannot activate/deactivate itself.

Convert a normal (not LDAP) user to LDAP user

PUT /users/ID/convert_to_ldap.json

The request body must include the 'login_dn' for the user:

{
  "login_dn": "CN=Jane,CN=Users,DC=tpm,DC=local"
}

If successful, the response code is 204 No content and the response body is empty.

* Note: a normal (not LDAP) user can convert itself to LDAP user.

Convert an LDAP user to normal

PUT /users/ID/convert_to_normal.json

The request body is empty.

If successful, the response code is 204 No content and the response body is empty.

* Notes: 1) a user can convert itself to LDAP user, 2) it is advised to change the password for the converted user (a previous password, if any, is not valid anymore).

Delete a user

DELETE /users/ID.json

If successful, the response code is 204 No content and the response body is empty.