API: Users

Current Team Password Manager version: 12.162.284

API v5

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",
    "last_login": "2021-08-25 16:09:49",
    "last_api_request": "2020-01-30 09:05:00",
    "is_active": true,
    "is_ldap": true,
    "is_saml": false,
    "is_api_only": false,
    "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",
    "last_login": "2021-08-25 17:12:24",
    "last_api_request": null,
    "is_active": true,
    "is_ldap": false,
    "is_saml": false,
    "is_api_only": false,
    "is_2fa_enabled": false,
    "valid_hash": true,
    "num_groups": 1
  },
...
]

* Note: if "is_ldap" and "is_saml" are both true, it means that the user authenticates using SAML but is defined as an LDAP user so it can be provisioned using LDAP sync. See Provisioning SAML users via LDAP for more information.

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,
  "is_saml": false,
  "is_api_only": false,
  "can_create_projects_in_root": true,
  "ldap_server_id": 0,
  "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"
  }
}

Show me (who am I)

This method returns all the data of the user making the request.

GET /users/me.json

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

The response body is like the one returned by GET /users/ID.json (show_user).

Create a normal (not LDAP, not SAML) user

Creates a normal (not LDAP, not SAML) user. Note that this method, in past versions of the API, was also used to create LDAP users. This is not the case any more, it's only used to create normal users. To create LDAP users you must use POST /users_ldap.json (see the next method).

POST /users.json

The request body must include the data for the user:

{
  "username": "johnnotboss",
  "email_address": "john@test.com",
  "name": "John",
  "role": "project manager",
  "password": "testpassword",
  "can_create_projects_in_root": true
}

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', 'role' (case insensitive: 'admin', 'project manager', 'normal user', 'read only' or 'only read', 'it') and 'password'.

The following field is optional: 'can_create_projects_in_root' (true/false). If not used, it will use the default value (see the PM_IT_CAN_CREATE_PRJS_ROOT parameter). If it's used when creating non IT/Project Manager users, it will be ignored.

Create an LDAP user

Creates an LDAP user.

POST /users_ldap.json

The request body must include the data for the user:

{
  "username": "johnnotboss",
  "email_address": "john@test.com",
  "name": "John",
  "role": "project manager",
  "ldap_server_id": 1,
  "login_dn": "cn=johnnotboss,ou=users,dc=ds,dc=mycompany,dc=com"
  "can_create_projects_in_root": true
}

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

{
  "id": 15
}

To be able to create an LDAP user, LDAP authentication must be enabled and the LDAP server id (1 to 9) must exist.

Create a SAML user

Creates a SAML user.

POST /users_saml.json

The request body must include the data for the user:

{
  "username": "johnnotboss",
  "email_address": "john@test.com",
  "name": "John",
  "role": "project manager",
  "can_create_projects_in_root": true
}

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').

To be able to create a SAML user, SAML authentication must be enabled.

Update a user

Updates a user, of any type (normal, LDAP or SAML).

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'), 'can_create_projects_in_root' (true/false), 'ldap_server_id' (1/9) and 'login_dn' (if the user is an LDAP user).

* Notes:

'can_create_projects_in_root' is ignored if the user being updated doesn't have the IT or Project Manager role.
'ldap_server_id' and 'login_dn' can only be set to update LDAP users. Otherwise the request will return an error.
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 an LDAP user

Converts a normal (not LDAP) user to an LDAP user.

PUT /users/ID/convert_to_ldap.json

The request body must include the 'ldap_server_id' (1/9) and login_dn' for the user:

{
  "ldap_server_id": 1,
  "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 a normal (not SAML) user to a SAML user

Converts a normal (not SAML) user to a SAML user.

PUT /users/ID/convert_to_saml.json

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

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

Convert an LDAP or SAML 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 normal 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.

Document changelog

Nov 12, 2021:

Document created

Questions or Problems? Please contact our support department