Testimonials
What our customers say about Team Password Manager

API: Users

Current Team Password Manager version: 13.166.291

API v6

Sections: List users | Show a user | Show me (who am I) | Create a user | Create an LDAP user | Create a SAML user | Update a user | Change the password of a user | Activate/deactivate a user | Convert a normal (not LDAP) user to an LDAP user | Convert a normal (not SAML) user to a SAML user | Convert an LDAP or SAML user to normal | List of passwords that a user has access to | List of projects that a user has access to | Delete a user


List users

Returns the users in Team Password Manager:

GET /users.json (all the users)
GET /users/search/urlencoded_string.json (see notes below)

The response from these request is paginated and /count.json, /page/num.json and X-Page-Size 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": 6,
        "name": "Alan Hall",
        "username": "alan",
        "email_address": "alan@teampasswordmanager.com",
        "role": "Project manager",
        "last_login": null,
        "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,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:07",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:37:58"
    },
    {
        "id": 3,
        "name": "Claire Wood",
        "username": "claire",
        "email_address": "claire@teampasswordmanager.com",
        "role": "Project manager",
        "last_login": null,
        "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,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:06",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:37:58"
    },
...
]

Notes:

  • 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.
  • Search:
    • Search is done in any of the users fields.
    • You need to urlencode the "urlencoded_string" part.
    • Example (in PHP):
      $search_string = '@teampasswordmanager'; // Find users that have "@teampasswordmanager" in any of the fields
$search_string_urlencoded = urlencode($search_string);
$request_url = 'https://YOUR_TPM_URL/index.php/api/v6/users/search/' . $search_string_urlencoded . '.json';

Metadata only lists

All users list requests can include the following header: X-Metadata-Only: true. When this header is used, the response will only include the metadata fields of the users. For example:

[
    {
        "id": 6,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:07",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:37:58"
    },
    {
        "id": 3,
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:06",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 14:37:58"
    },
    ...
]

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"
  }
}

* 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.


Metadata only

The show a user request can include the following header: X-Metadata-Only: true. When this header is used, the response will only include the metadata fields of the user. For example:

{
    "id": 6,
    "created_by": {
        "id": 1
    },
    "created_on": "2024-12-16 14:36:07",
    "updated_by": {
        "id": 1
    },
    "updated_on": "2024-12-16 14:37:58"
}

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

The X-Metadata-Only: true header can also be used in this request.


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
}

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'), 'ldap_server_id' (1-9) and 'login_dn'.

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.

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

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.

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


List of passwords that a user has access to

This request returns the list of passwords that a user (identified by its internal id) has access to.

GET /users/ID/passwords.json

The responses from these requests are paginated and /count.json, /page/num.json and X-Page-Size can be used. See the section on pagination for more information. Example: GET /passwords/page/2.json

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

Example response body:

[
    {
        "id": 70,
        "name": "Wordpress admin",
        "project": {
            "id": 1,
            "name": "Clients"
        },
        "project_full_path": [
            {
                "id": 1,
                "name": "Clients",
                "archived": false
            }
        ],
        "notes_snippet": "Some notes for the wp admin credentials.",
        "tags": "wordpress",
        "access_info": "http:\/\/www.fictionalgadgetsite.com\/wp-admin",
        "username": "admin_sg",
        "email": "",
        "has_password": false,
        "strength": "good",
        "expiry_date": "2024-12-31",
        "expiry_status": 3,
        "archived": false,
        "project_archived": false,
        "favorite": false,
        "num_files": 2,
        "locked": false,
        "locking_type": 0,
        "external_sharing": false,
        "linked": true,
        "source_password_id": 68,
        "managed_by": {
            "id": 1
        },
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:08",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-18 07:13:51"
    },
    {
        "id": 64,
        "name": "Amazon",
        "project": {
            "id": 18,
            "name": "www.fictionalgadgetsite.com"
        },
        "project_full_path": [
            {
                "id": 6,
                "name": "Internal",
                "archived": false
            },
            {
                "id": 5,
                "name": "Company projects",
                "archived": false
            },
            {
                "id": 18,
                "name": "www.fictionalgadgetsite.com",
                "archived": false
            }
        ],
        "archived": false,
        "project_archived": false,
        "favorite": false,
        "locked": true,
        "locking_type": 1,
        "linked": false,
        "managed_by": {
            "id": 1
        },
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:08",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-17 17:05:24"
    },
    ...
]

This list has the same fields and properties as the list passwords requests, including: the use of the X-Metadata-Only: true header to return the metadata fields of the passwords only, and the use of the X-Permissions: true header to return the permissions assigned to each password.

Note that this request can only be executed by users with the Admin role.


List of projects that a user has access to

This request returns the list of projects that a user (identified by its internal id) has access to.

GET /users/ID/projects.json

The responses from these requests are paginated and /count.json, /page/num.json and X-Page-Size can be used. See the section on pagination for more information. Example: GET /passwords/page/2.json

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

Example response body:

[
    {
        "id": 18,
        "name": "www.fictionalgadgetsite.com",
        "full_path": [
            {
                "id": 6,
                "name": "Internal",
                "archived": false
            },
            {
                "id": 5,
                "name": "Company projects",
                "archived": false
            },
            {
                "id": 18,
                "name": "www.fictionalgadgetsite.com",
                "archived": false
            }
        ],
        "tags": "client",
        "archived": false,
        "favorite": false,
        "num_files": 2,
        "managed_by": {
            "id": 3,
            "name": "Claire Wood"
        },
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:08",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-18 07:03:39"
    },
    {
        "id": 5,
        "name": "Company projects",
        "full_path": [
            {
                "id": 6,
                "name": "Internal",
                "archived": false
            },
            {
                "id": 5,
                "name": "Company projects",
                "archived": false
            }
        ],
        "tags": "project",
        "archived": false,
        "favorite": false,
        "num_files": 0,
        "managed_by": {
            "id": 1,
            "name": "John Boss"
        },
        "created_by": {
            "id": 1
        },
        "created_on": "2024-12-16 14:36:08",
        "updated_by": {
            "id": 1
        },
        "updated_on": "2024-12-16 19:00:24"
    },
    ...
]

This list has the same fields and properties as the list projects requests, including: the use of the X-Metadata-Only: true header to return the metadata fields of the projects only, and the use of the X-Permissions: true header to return the permissions assigned to each project.

Note that this request can only be executed by users with the Admin role.


Delete a user

DELETE /users/ID.json

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


Document changelog

Dec 19, 2024: Document created from API v5
Check the API changelog for changes
Questions or Problems? Please contact our support department