API v3
Sections: List users | Show a user | Show me (who am I) | 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" } }
* Note: if using version 6.68.138+, an LDAP user will not show the server, only the Login DN.
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 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).
* Note: if using version 6.68.138+, the LDAP server assigned is "Server 1". With this version of the API other servers cannot be assigned.
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.
* Note: if using version 6.68.138+, the LDAP server assigned is "Server 1". With this version of the API other servers cannot be assigned.
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.