Testimonials
What our customers say about Team Password Manager

API: Projects

Current Team Password Manager version: 12.160.277

API v5

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
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 and /page/num.json 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": 24,
    "name": "Project created with the API",
    "tags": "client,seo,website",
    "managed_by": {
      "id": 1,
      "name": "John Boss"
    },
    "archived": false,
    "favorite": true,
    "num_files": 0,
    "updated_on": "2014-07-04 14:02:14"
  },
  {
    "id": 12,
    "name": "www.fictionalgadgetsite.com",
    "tags": "client",
    "managed_by": {
	    "id": 3,
	    "username": "claire",
	    "email_address": "claire@teampasswordmanager.com",
	    "name": "Claire Wood",
	    "role": "Project manager"
	},
    "archived": false,
    "favorite": false,
    "num_files": 0,
    "updated_on": "2014-07-03 19:13:37"
  }
]

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/v5/projects/search/' . $search_string_urlencoded . '.json';

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": 20,
  "name": "www.mynewsite.com",
  "parent_id": 19,
  "tags": "",
  "notes": "SEO for www.mynewsite.com.",
  "managed_by": {
    "id": 2,
    "username": "alan",
    "email_address": "alan@teampasswordmanager.com",
    "name": "Alan",
    "role": "Project manager"
  },
  "grant_all_permission": {
    "id": -1,
    "label": "(Do not set)"
  },
  "users_permissions": [
    {
      "user": {
        "id": 3,
        "username": "ann",
        "email_address": "ann@teampasswordmanager.com",
        "name": "Ann",
        "role": "Normal user"
      },
      "permission": {
        "id": 50,
        "label": "Read \/ Manage passwords"
      }
    }
  ],
  "groups_permissions": [
    {
      "group": {
        "id": 1,
        "name": "SEO"
      },
      "permission": {
        "id": 20,
        "label": "Read"
      }
    }
  ],
  "num_passwords": 1,
  "num_files": 1,
  "user_permission": {
    "id": 60,
    "label": "Manage"
  },
  "user_can_create_passwords": true,
  "is_leaf": true,
  "parents": [
    13,
    19
  ],
  "archived": false,
  "favorite": true,
  "created_on": "2015-08-16 02:16:49",
  "created_by": {
    "id": 1,
    "username": "john",
    "email_address": "john@teampasswordmanager.com",
    "name": "John Boss",
    "role": "Admin"
  },
  "updated_on": "2015-08-16 08:37:14",
  "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 to groups_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.

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 and /page/num.json 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": 69,
    "name": "Google account",
    "project": {
      "name": "www.mynewsite.com"
    },
    "notes_snippet": "",
    "tags": "google",
    "access_info": "https:\/\/www.google.com",
    "username": "thisisme",
    "email": "thisisme@mynewsite.com",
    "has_password": true,
    "expiry_date": null,
    "expiry_status": 0,
    "archived": false,
    "project_archived": false,
    "favorite": false,
    "num_files": 0,
    "locked": false,
    "locking_type": 0,
    "external_sharing": false,
    "linked": false,
    "updated_on": "2015-08-16 08:37:52"
  },
...
]

Notes:

  • 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.
  • Locked passwords (locked=true) will not show any data except id, name, project, archived, project_archived, favorite, locked, locking_type external_sharing, linked and updated on.
  • 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.

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 and /page/num.json 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": 65,
    "filename": "mouse.jpg",
    "size_bytes": 82935,
    "size_txt": "80.99 kb",
    "notes_snippet": "A little ...",
    "updated_on": "2021-07-15 13:00:48"
  },
  {
    "id": 58,
    "filename": "server_room_map.pdf",
    "size_bytes": 92655,
    "size_txt": "90.48 kb",
    "notes_snippet": "",
    "updated_on": "2019-04-25 13:37:00"
  }
]

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 v5 URL
  $tpm_base_url  = 'https://YOUR_TPM_URL/index.php/api/v5';

  // 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

May 30, 2023: Since v. 12.143.260, when deleting a project, it's moved to the Trash Bin.
Nov 12, 2021: Document created
Questions or Problems? Please contact our support department