Testimonials
What our customers say about Team Password Manager

API changes in V6

Hi,

Some of you have asked us what changes will V6 bring to the API. If there'll be a new API version. If the current API versions will work. And so on. So we've decided to write this post explaining these changes:

1. API v1 and v2 will no longer be available

These have been available for a long time and maintaining them doesn't make sense with the new permissions and hierarchy model. Also, you can easily convert v1 and v2 projects to v3 without much hassle.

2. API v3 (the latest API version) will still be available

But it will be marked as deprecated and will be discontinued in future versions of Team Password Manager. Internally, to adapt to the new permissions and hierarchy model, some changes have been made. The interface will basically be the same, but its functionality will be limited with the new model. These are the things you'll need to consider (you might want to check the screenshots at the end of the post to understand some of the new features):

In projects:

  • show project:
    • everyone_has_access=TRUE if grant all is set to a value (even if "No access"). If grant all is inherited, this gets the value from the parent.
    • users_access/groups_access array have user/group that is set a permission (even if "No access").
    • user_permission can be "Traverse", "Read", "Read / Create passwords", "Read / Edit passwords data", "Read / Manage passwords" or "Manage".
  • list users who can access a project: access_type can be "No access", "Traverse", "Read", "Read / Create passwords", "Read / Edit passwords data", "Read / Manage passwords" or "Manage".
  • create/update project:
    • if everyone_has_access is set it will set a "Read / Create passwords" permission on the project for all the users (grant all in V6).
    • users/groups in users_access/groups_access will be set "Read / Create passwords" permission on the project (except for read only users that will be set "Read" permission).
    • "managed_by" users can be normal users too (not only users with role IT/Project manager/Admin).
  • delete a project: only leaf projects can be deleted.

In passwords:

  • show password:
    • everyone_has_access=TRUE if grant all is set to a value (even if "No access") in project.
    • users_access/groups_access array have user/group that is set a permission (even if "No access").
    • user_permission can be "Read", "Edit data" or "Manage".
  • list users who can access a password: access_type can be "No access", "Read", "Edit data" or "Manage".
  • create passwords: only users with the following permissions in a project can create passwords in the project: "Read / Create passwords", "Read / Edit passwords data", "Read / Manage passwords" and "Manage".
  • update passwords: users with "Edit data" permission can update the password (not only the ones with "Manage" permission).
  • update security:
    • users/groups in users_access/groups_access will be set "Manage" permission on the password (except for read only users that will be set "Read" permission - that was already being done).
    • "managed_by" can also be any user (except read only users), not just users that have access to the password.
  • update security, update custom fields definitions, delete, lock/unlock: the user making the request needs to have Manage permission.

3. API v4 will be the new API version

This new version will be able to work with the new permissions and hierarchy model at its fullest. Here you have the changes and new additions that it will bring:

In projects

  • NEW: subprojects: immediate subprojects of a project (or root). GET /projects/ID/subprojects.json => subprojects of project ID (0 for root). GET /projects/ID/subprojects/ACTION.json => (ACTION=new_pwd) subprojects of project ID (0 for root) with info about projects that a password cannot be created in for the user (disabled field in response).
    • Sorted by project name.
    • Same info as the one in the projects tree in the interface.
    • Not all users see the same tree.
    • Not paginated.
    • Read only users can also list them.
  • show project: new and changed fields in the response:
    • NEW: parent_id: the id of the parent of the project (the real parent, not the parent "seen" by the user).
    • grant_all_permission instead of everyone_has_access: the permission granted to all the users.
    • users_permissions instead of users_access. Includes also the permission set.
    • groups_permissions instead of groups_access. Includes also the permission set.
    • user_permission is now a permission object.
    • NEW: is_leaf (true/false): tells if the project is a leaf node or not. Real leaf, not as seen by the user.
    • NEW: parents: array of parent ids from to the root to the current project (in descending order), as seen by the user. Null if the project is seen as root by the user.
  • list of users who can access a project (security):
    • access_type is now called permission and it's a permission object.
    • NEW: granted_via: how the user is granted the permission (descriptive).
  • create a project:
    • NEW: parent_id: the id of the parent project (0 if root).
    • No security fields are allowed, only name (required), parent_id (required), tags and notes. Use update security to change permissions.
  • update a project:
    • parent_id cannot be specified.
    • No security fields are allowed, only name (required), tags and notes. Use update security to change permissions.
  • NEW: update security of a project (PUT /projects/ID/security.json). Allowed fields:
    • 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. For Read only users these are the only valid permissions: 0, 10, 20, 99.
    • groups_permissions: array of [group_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. If you want to set (-1: Do not set), simply exclude the group from the list.

In passwords

  • list passwords: new field: "external_sharing" (true/false) true=the passwords is shared externally.
  • show password:
    • everyone_has_access is no longer available. Reason: misleading. Permission fields in show password should only show what's set in the password.
    • users_permissions instead of users_access. Includes also the permission set.
    • groups_permissions instead of groups_access. Includes also the permission set.
    • user_permission is now a permission object.
    • external_sharing: true/false.
    • external_url: if external_sharing is true, the url to access the password externally. If not, null.
  • list of users who can access a password (security):
    • access_type is now called permission and it's a permission object.
    • NEW: granted_via: how the user is granted the permission (descriptive).
  • update security of a password. Changes:
    • users_permissions instead of users_access: array of [user_id, permission_id]. User permissions will be set for the users passed, deleting the current permissions. permission_id can be: 0=no acces, 10=read, 20=edit data, 30=manage (only 0, 10 for users with role read only). If you want to set "Do not set", simply exclude the user. Admin users, the project manager(s) and the password manager can be included in this list, but it will have no effect. For Read only users these are the only valid permissions: 0, 10.
    • groups_permissions instead of groups_access: array of [group_id, permission_id]. Groups permissions will be set for the groups passed, deleting the current permissions. permission_id can be: 0=no acces, 10=read, 20=edit data, 30=manage. If you want to set "Do not set", simply exclude the group from the list.

Note: a permission object is an object {id, "label"} describing a permission. Example: {30, "Manage"}.

----

These can seem a lot of changes, but basically they reflect the change of the internal model: from access/no access to a permissions based one, and to hierarchy in projects. For reference, here you have the "Edit Project Security" and "Edit Password Security" screens in V6:

Edit project security in V6 Edit password security in V6

Obviously, the full documentation for both API v3 and v4 will be available in the usual format (not just as a changelog as presented here) when we release V6. We just wanted to give you a heads up on the changes ahead.

Jul 6 2015 by Ferran Barba