Testimonials
What our customers say about Team Password Manager

API v4: Projects

Current Team Password Manager version: 13.166.291

API v4

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 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/v4/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.
  • 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",
    "expiry_date": null,
    "expiry_status": 0,
    "archived": false,
    "favorite": false,
    "num_files": 0,
    "locked": false,
    "external_sharing": false,
    "updated_on": "2015-08-16 08:37:52"
  },
...
]

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.

Document changelog

May 30, 2023: Since v. 12.143.260, when deleting a project, it's moved to the Trash Bin.
Jun 26, 2020: Clarification of what to encode when searching in "List projects"
Questions or Problems? Please contact our support department