API v6
Sections: List projects | List subprojects | Show a project | List passwords of a project | List of users who can access a project | Create a project | Update a project | Change the parent of a project | Update the security of a project | Archive/un-archive a project | Delete a project | List files of a project | Upload a file to a project
List projects
These return the projects that the user has access to. The returned data is the same as in the projects lists (all active, archived, favorite and search) in the web interface.
GET /projects.json (active projects) GET /projects/all.json GET /projects/archived.json GET /projects/favorite.json GET /projects/search/urlencoded_string.json (see notes below)
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 /projects/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": 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, "username": "john", "email_address": "john@teampasswordmanager.com", "name": "John Boss", "role": "Admin" }, "created_by": { "id": 1 }, "created_on": "2024-12-16 14:36:08", "updated_by": { "id": 1 }, "updated_on": "2024-12-16 19:00:24" }, { "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": 0, "managed_by": { "id": 3, "username": "claire", "email_address": "claire@teampasswordmanager.com", "name": "Claire Wood", "role": "Project manager" }, "created_by": { "id": 1 }, "created_on": "2024-12-16 14:36:08", "updated_by": { "id": 1 }, "updated_on": "2024-12-16 14:36:08" }, ... ]
Note: full_path
shows the path to the current project, as seen by the user. It includes the project as the last one.
Notes on search:
- You need to urlencode the "urlencoded_string" part.
- Example (in PHP):
$search_string = 'website'; // Find projects that contain "website" $search_string_urlencoded = urlencode($search_string); $request_url = 'https://YOUR_TPM_URL/index.php/api/v6/projects/search/' . $search_string_urlencoded . '.json';
Metadata only lists
All project 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 projects. For example:
[ { "id": 5, "managed_by": { "id": 1 }, "created_by": { "id": 1 }, "created_on": "2024-12-16 14:36:08", "updated_by": { "id": 1 }, "updated_on": "2024-12-16 19:00:24" }, { "id": 18, "managed_by": { "id": 3 }, "created_by": { "id": 1 }, "created_on": "2024-12-16 14:36:08", "updated_by": { "id": 1 }, "updated_on": "2024-12-16 14:36:08" }, ... ]
Metadata only lists are much quicker than the normal lists.
Permissions lists
All project list requests can include the following header: X-Permissions: true
. When this header is used, the response will only include the fields that refer to the permissions assigned to users and groups for the project. These fields are: grant_all_permission
, managed_by
, users_permissions
and groups_permissions
. All of these fields are the same fields as in the show a project request, but here only the ids are returned, for speed. The metadata fields are included for completeness. For example:
[ { "id": 18, "grant_all_permission": { "id": -1, "label": "(Do not set)" }, "users_permissions": [ { "user": { "id": 2 }, "permission": { "id": 20, "label": "Read" } }, { "user": { "id": 8 }, "permission": { "id": 50, "label": "Read \/ Manage passwords" } } ], "groups_permissions": [ { "group": { "id": 1 }, "permission": { "id": 10, "label": "Traverse" } }, { "group": { "id": 2 }, "permission": { "id": 10, "label": "Traverse" } } ], "managed_by": { "id": 3 }, "created_by": { "id": 1 }, "created_on": "2024-12-16 14:36:08", "updated_by": { "id": 1 }, "updated_on": "2024-12-17 11:26:55" }, { "id": 5, "grant_all_permission": { "id": -1, "label": "(Do not set)" }, "users_permissions": null, "groups_permissions": [ { "group": { "id": 1 }, "permission": { "id": 10, "label": "Traverse" } }, { "group": { "id": 2 }, "permission": { "id": 30, "label": "Read \/ Create passwords" } } ], "managed_by": { "id": 1 }, "created_by": { "id": 1 }, "created_on": "2024-12-16 14:36:08", "updated_by": { "id": 1 }, "updated_on": "2024-12-16 19:00:24" }, ... ]
Notes:
- Requests with the
X-Permissions: true
header are only available to Admin users. - The
X-Permissions: true
header has priority over theX-Metadata-Only: true
header.
List subprojects
These return the immediate subprojects of a project (or root) that the user has access to.
GET /projects/ID/subprojects.json GET /projects/ID/subprojects/ACTION.json
Where:
- ID: internal id of the project, 0 for root (will return first level projects).
- ACTION: currently can only be
new_pwd
. When used, the "disabled" field in the response will be set to true for those projects where the user cannot create passwords.
If successful, the response code is 200 OK
with the results of the call in the response body.
Example response body:
[ { "id": 13, "name": "Clients", "has_children": true, "archived": false, "favorite": false, "disabled": false, "num_pwds": 1, "num_pwds_branch": 33 }, { "id": 17, "name": "Company projects", "has_children": true, "archived": false, "favorite": false, "disabled": false, "num_pwds": 0, "num_pwds_branch": 16 }, { "id": 14, "name": "Internal", "has_children": true, "archived": false, "favorite": false, "disabled": false, "num_pwds": 0, "num_pwds_branch": 21 } ]
Notes:
num_pwds
contains the number of passwords of the project that the user has access to.num_pwds_branch
contains the number of passwords of the project and its subprojects (if any) that the user has access to.- The response list is sorted by project name.
- The information returned is the same as in the projects tree in the web interface.
- Not all users "see" the same tree. Only Admins have the complete view. Users that are not Admins can see a different tree depending on their permissions.
- Results are not paginated.
- Read only users can also use this method.
Show a project
This method returns all the data of a project, identified by its internal id.
GET /projects/ID.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", "parent_id": 5, "tags": "client", "notes": "", "managed_by": { "id": 3, "username": "claire", "email_address": "claire@teampasswordmanager.com", "name": "Claire Wood", "role": "Project manager" }, "users_permissions": [ { "user": { "id": 2, "username": "frank", "email_address": "frank@teampasswordmanager.com", "name": "Frank Steel", "role": "Normal user" }, "permission": { "id": 20, "label": "Read" } }, { "user": { "id": 8, "username": "tom", "email_address": "tom@teampasswordmanager.com", "name": "Tom Landy", "role": "Normal user" }, "permission": { "id": 50, "label": "Read \/ Manage passwords" } } ], "groups_permissions": [ { "group": { "id": 1, "name": "Web work" }, "permission": { "id": 10, "label": "Traverse" } }, { "group": { "id": 2, "name": "IT work" }, "permission": { "id": 10, "label": "Traverse" } } ], "grant_all_permission": { "id": -1, "label": "(Do not set)" }, "num_passwords": 8, "num_files": 0, "user_permission": { "id": 60, "label": "Manage" }, "user_can_create_passwords": true, "is_leaf": true, "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, "favorite": false, "created_on": "2024-12-16 14:36:08", "created_by": { "id": 1, "username": "john", "email_address": "john@teampasswordmanager.com", "name": "John Boss", "role": "Admin" }, "updated_on": "2024-12-17 11:26:55", "updated_by": { "id": 1, "username": "john", "email_address": "john@teampasswordmanager.com", "name": "John Boss", "role": "Admin" } }
Notes:
parent_id
is the id of the parent of the project. The real parent, not the parent "seen" by the user.grant_all_permission
is a permission object (permission id, permission description) that indicates the permission granted to all the users.users_permissions
is an array of objects that tell the permission set to a user. It contains an user object and a permission object. The same applies togroups_permissions
but for groups. These data are only available to users with manage permission on the project (they're set to null for users that don't have the manage permission)user_can_create_passwords
indicates if the user making the request can create passwords on the project. It can be true or false.user_permission
is a permission object (permission id, permission description) that indicates which permission has the user on the project.is_leaf
(true/false) tells if the project is a leaf node or not. Real leaf, not as seen by the user.parents
is an array of project ids from to the root to the current project (not included) (in descending order), as seen by the user. Null if the project is seen as root by the user.- The
parents
field is no longer available, it has been replaced byfull_path
. full_path
shows the path to the current project, as seen by the user. It includes the current project as the last one.
List passwords of a project
This method returns the passwords of a project, identified by its internal id. This call shows the same data as the "Passwords" tab of a project.
GET /projects/ID/passwords.json
The response from this 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 /projects/12/passwords/count.json
If successful, the response code is 200 OK
with the results of the call in the response body.
Example response body:
[ { "id": 68, "name": "Wordpress admin", "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 } ], "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": true, "strength": "good", "expiry_date": "2024-12-31", "expiry_status": 3, "archived": false, "project_archived": false, "favorite": false, "num_files": 0, "locked": false, "locking_type": 0, "external_sharing": false, "linked": false, "source_password_id": 0, "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 12:09:42" }, { "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 12:09:19" }, ... ]
Notes:
project_full_path
shows the path to the project of the password, as seen by the user. It includes the project of the password as the last one. It's the same field asfull_path
in projects lists.expiry_date
uses ISO 8601 format: yyyy-mm-dd.expiry_status
has the following values: 0=no date or not expired, 1=expires today, 2=expired, 3=will expire soon.has_password
is true if the password entry has the password datum filled in. To view it you need to use the show a password method.strength
can have the following values: "" (none), "very weak", "weak", "good" and "strong".- Locked passwords (
locked
=true) will not show any data except id, name, project, archived, project_archived, favorite, locked, locking_type external_sharing, linked and the metadata fields. locking_type
has the following values: 0=password not locked, 1=requires a reason to unlock, 2=requires permission to unlock.- Linked passwords:
linked
=true if the password is a linked password. archived
=true if the password is archived and/or the project is archived.project_archived
=true if the project is archived.
Metadata only list
The list passwords of a project 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 passwords. For example:
[ { "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-17 17:05:42" }, { "id": 64, "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" }, ... ]
Metadata only lists are much quicker than the normal lists.
Permissions list
The list passwords of a project requests can include the following header: X-Permissions: true
. When this header is used, the response will only include the fields that refer to the permissions assigned to users and groups for the password. These fields are: managed_by
, users_permissions
and groups_permissions
. All of these fields are the same fields as in the show a password request, but here only the ids are returned, for speed. The metadata fields are included for completeness. For example:
[ { "id": 68, "users_permissions": [ { "user": { "id": 2 }, "permission": { "id": 10, "label": "Read" } }, { "user": { "id": 4 }, "permission": { "id": 30, "label": "Manage" } }, { "user": { "id": 8 }, "permission": { "id": 20, "label": "Edit data" } } ], "groups_permissions": [ { "group": { "id": 3 }, "permission": { "id": 0, "label": "No access" } }, { "group": { "id": 4 }, "permission": { "id": 30, "label": "Manage" } } ], "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:42" }, { "id": 64, "users_permissions": null, "groups_permissions": null, "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" }, ... ]
Notes:
- Requests with the
X-Permissions: true
header are only available to Admin users. - The
X-Permissions: true
header has priority over theX-Metadata-Only: true
header. - For locked passwords,
users_permissions
andgroups_permissions
are null.
List users who can access a project
This method returns the effective permissions users have on a project. This call shows similar data as the "Security" tab of the project.
GET /projects/ID/security.json
If successful, the response code is 200 OK
with the results of the call in the response body.
The response is an array of objects that have the following data:
- User object: data about the user.
- Permission object: permission id and description.
- Granted via: how the user is granted the permission on the project.
Example response body:
[ { "user": { "id": 2, "username": "alan", "email_address": "alan@teampasswordmanager.com", "name": "Alan", "role": "Project manager" }, "permission": { "id": 60, "label": "Manage" }, "granted_via": "Project manager" }, { "user": { "id": 4, "username": "amy", "email_address": "amy@teampasswordmanager.com", "name": "Amy", "role": "Normal user" }, "permission": { "id": 20, "label": "Read" }, "granted_via": "Group: SEO" }, { "user": { "id": 3, "username": "ann", "email_address": "ann@teampasswordmanager.com", "name": "Ann", "role": "Normal user" }, "permission": { "id": 50, "label": "Read \/ Manage passwords" }, "granted_via": "User direct" }, { "user": { "id": 1, "username": "john", "email_address": "john@teampasswordmanager.com", "name": "John Boss", "role": "Admin" }, "permission": { "id": 60, "label": "Manage" }, "granted_via": "Admin rights" } ]
Create a project
POST /projects.json
The request body must include the data for the project (name and parent_id are required):
{ "name": "Name of the project", "parent_id": 20, "tags": "tag1,tag2,tag3", "notes": "some notes" }
If successful, the response code is 201 Created
with the internal id of the project in the response body:
{ "id": 41 }
The following fields can be used when creating a project: 'name' (required), 'parent_id' (required: the parent of the project, 0 for root), 'tags' (list of comma separated strings), 'notes'.
Update a project
PUT /projects/ID.json
The request body must include the data for the project. Only the fields that are included are updated, the other fields are left unchanged:
{ "name": "Name of the project", "tags": "tag1,tag2,tag3", "notes": "some notes" }
If successful, the response code is 204 No content
and the response body is empty.
The following fields can be used when updating a project: 'name', 'tags' (list of comma separated strings) and 'notes'.
Notes: the 'name', if present, can't be empty. 'parent_id' cannot be used here, it's only used when creating the project.
Change the parent of a project
Sets a new parent for the project.
PUT /projects/ID/change_parent.json
The request body must include the data for the new parent:
{ "parent_id": 123 }
For root projects, set parent_id to 0.
If successful, the response code is 204 No content
and the response body is empty.
Update the security of a project
Sets the main manager of the project and grants permissions to users and groups. Does the same as the "Security" button of the project in the web interface (Edit Project Security).
PUT /projects/ID/security.json
The request body must include the data for the project's security. Allowed fields in the request body are:
managed_by
id of the user that is to be the main manager. Can be any user except read only users.grant_all_permission
id of the permission to grant all users. Allowed values:
-1 - (Do not set): set permissions for individual users/groups, not globally.
0 - No access: the user/group cannot access the project or any of its passwords.
10 - Traverse: the user/group can see the project name only.
20 - Read: the user/group can only read project data and its passwords.
30 - Read / Create passwords: the user/group can read project data and create passwords in it.
40 - Read / Edit passwords data: the user/group can read project data and edit the data of its passwords (and also create passwords).
50 - Read / Manage passwords: the user/group can read project data and manage its passwords (and also create passwords).
60 - Manage: the user/group has total control over the project and its passwords.
99 - Inherit from parent: the user/group will inherit the permission set on the parent project. Cannot be set if the project is a root project.
users_permissions
array of [user_id, permission_id]. User permissions will be set for the users passed, deleting the current permissions. permission_id can be: 0, 10, 20, 30, 40, 50, 60, 99 (only 0, 10, 20, 99 for users with role read only). If you want to set (-1: Do not set), simply exclude the user. Admin users and the project manager can be included in this list, but it will have no effect.groups_permissions
array of [group_id, permission_id]. Groups permissions will be set for the groups passed, deleting the current permissions. permission_id can be:0, 10, 20, 30, 40, 50, 60, 99. If you want to set (-1: Do not set), simply exclude the group from the list.
Note: grant_all_permission has precedence over users_permissions and groups_permissions.
Example of a request body:
{ "managed_by": 4, "grant_all_permission": -1, "users_permissions": [ [2,60], [3,10] ], "groups_permissions": [ [1,40] ] }
If successful, the response code is 204 No content
and the response body is empty.
Archive/un-archive a project
PUT /projects/ID/archive.json
PUT /projects/ID/unarchive.json
If successful, the response code is 204 No content
and the response body is empty.
Delete a project
DELETE /projects/ID.json
This deletes the project, its passwords, files, etc.
If successful, the response code is 204 No content
and the response body is empty.
Notes:
- Only leaf projects can be deleted.
- Only users with role Admin, IT or Project Manager can delete projects. Users with role Normal, even if they're the manager of the project, cannot delete it.
- Since v. 12.143.260, the project and its passwords are moved to the Trash Bin.
List files of a project
This method returns the files uploaded to a project. This call shows similar data as the "Files" tab of the project.
GET /projects/ID/files.json
The response from this 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 /projects/ID/files/page/2.json
If successful, the response code is 200 OK
with the results of the call in the response body.
The response is an array of objects that have the following data: id (each file has a unique id in Team Password Manager, which you can see by clicking on the "Info" button of the file), filename, size in bytes and as it appears in the UI, a snippet of the notes if the file has them and when it was last updated.
Example response body:
[ { "id": 8, "filename": "quote_server_room_maintenance.pdf", "size_bytes": 72590, "size_txt": "70.89 kb", "notes_snippet": "", "uploaded_by": { "id": 1 }, "uploaded_on": "2024-12-18 07:03:39", "notes_updated_by": { "id": 1 }, "notes_updated_on": "2024-12-18 07:03:39" }, { "id": 7, "filename": "PXL_20241217_125411350.jpg", "size_bytes": 2017894, "size_txt": "1.92 mb", "notes_snippet": "Server...", "uploaded_by": { "id": 1 }, "uploaded_on": "2024-12-18 07:02:17", "notes_updated_by": { "id": 1 }, "notes_updated_on": "2024-12-18 07:02:28" } ]
Metadata only list
This list files of a project 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 files. For example:
[ { "id": 8, "uploaded_by": { "id": 1 }, "uploaded_on": "2024-12-18 07:03:39", "notes_updated_by": { "id": 1 }, "notes_updated_on": "2024-12-18 07:03:39" }, { "id": 7, "uploaded_by": { "id": 1 }, "uploaded_on": "2024-12-18 07:02:17", "notes_updated_by": { "id": 1 }, "notes_updated_on": "2024-12-18 07:02:28" } ]
Upload a file to a project
This method uploads a file to a project.
POST /projects/ID/upload.json
The request body must include the data for the file, which consists of three fields:
file_data_base64
contents of the file. It must be Base64 encoded. This field is required.file_name
name of the file. This field is required.notes
notes of the file. This field is optional.
Example request body:
{ "file_data_base64": "dGhpcyBpcyBhIHNpbXBsZSB0ZXh0IGZpbGU=", (Base64 encoded content of the file to upload) "file_name": "file_to_upload.pdf", "notes": "some notes for the file" }
If successful, the response code is 201 Created
with the internal id of the file in the response body:
{ "id": 373 }
Upload a file to a project example in PHP
The following script shows you how to upload a file to a project using PHP. To run it, save it to a PHP file and replace the variables on top with your own values:
<?php // API URL $tpm_base_url = 'https://YOUR_TPM_URL/index.php/api/v6'; // User with Manage permission on the project to upload the file to $username = 'YOUR_TPM_USERNAME'; $password = 'YOUR_TPM_PASSWORD'; // Project id of the project to upload the file to $prj_id = YOUR_PRJ_ID; // For example: 23 // File to upload, in the same folder as this script $file_to_upload = 'YOUR_FILE_NAME'; // For example: 'server_specs.pdf' // Read the file, encode it with Base64 and store it in $file $file = base64_encode(file_get_contents($file_to_upload)); if ( $file ) { // Method to upload $request_uri = '/projects/' . $prj_id . '/upload.json'; // Body with the data to upload the file (JSON encoded array) $request_body_json = json_encode(array( 'file_data_base64' => $file, 'file_name' => $file_to_upload, // Just the name of the file, do not include the path here 'notes' => 'Some notes' )); // Headers: JSON and UTF-8 $headers = array( 'Content-Type: application/json; charset=utf-8' ); // POST request $ch = curl_init($tpm_base_url . $request_uri); curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); curl_setopt($ch, CURLOPT_HEADER, FALSE); // Does not include header in the output curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, $request_body_json); curl_setopt($ch, CURLOPT_USERPWD, $username . ":" . $password); // HTTP Basic Authentication curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // Execute $result = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); // Show response echo 'Status: ' . $status . '
'; echo $result; } else { echo 'Incorrect file'; }
If successful, the result should show something like this, where "id" is the id of the newly created file:
Status: 201 {"id":380}
Document changelog
Dec 19, 2024: |
Document created from API v5 Check the API changelog for changes |