API v4: Change log

Changes in API v4

In passwords

Since v. 10.138.240, the "Show a password" method (GET /passwords/ID.json) returns the OTP value at the time of request in the "data" field for custom fields of type "One Time Password". Previously, in v. 10.135.236, the "data" field for this type of custom fields returned the Secret Key.

Changes from API v3 to API v4

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.
• NEW: change the parent of a project (PUT /projects/ID/change_parent.json).

In passwords

• list passwords: new field: "external_sharing" (true/false) true=the passwords is shared externally.
• show password:
• NEW: parents: array of project ids from to the root to the project of the password (in descending order), as seen by the user.
• 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"}.

Changes from API v2 to API v3

• New resource: Version, to get version information.
• New resource: My Passwords, to work with the personal passwords of the user (My Passwords).
• Get information about the user making the call (who am I): GET /users/me.json.
• GET /passwords/ID.json => additional returned field that indicates what permission has the user making the request on the password: "user_permission" can be read/manage.
• GET /projects/ID.json => additional returned field that indicates what permission has the user making the request on the project: "user_permission" can be read/manage.
• GET /projects/ID.json => additional returned field that indicates if the user making the request can create passwords on the project: "user_can_create_passwords" (true/false).
• Allow the use of the advanced search operators (in all versions of the API).
• Fix incorrect encoding of numeric strings as numbers in API responses (in all versions of the API) (released previsouly as patch 4.47.94.20150206).

Changes from API v1 to API v2

Basically, API v2 introduces support for expiry date and locking.

Specifically (this is also documented in the corresponding sections):

• List passwords (and List passwords of a project): expiry_date (in ISO 8601 format: yyyy-mm-dd), expiry_status (0=no date or not expired, 1=expires today, 2=expired, 3=will expire soon).
• Show a password: expiry_date (in ISO 8601 format: yyyy-mm-dd), expiry_status (0=no date or not expired, 1=expires today, 2=expired, 3=will expire soon).
• Create a password, Update a password: expiry_date (in ISO 8601 format: yyyy-mm-dd, or null or '').
• Support for locked passwords:
  • In lists: locked property (TRUE/FALSE) and can only see name and project.
  • In show: locked property (TRUE/FALSE) and can see more data than name and project if "X-Unlock-Reason" header supplied.
  • To lists users the "X-Unlock-Reason" header must be supplied. If not => 403 (forbidden).
  • To update (data, custom fields, security, delete, lock state): need to supply "X-Unlock-Reason" header. If not => 403 (forbidden).
  • Set a password as locked or not.
  • "X-Unlock-Reason" is only valid for the call, not the session (because there is no session).

In previous versions (v1):

• expiry_date and expiry_status are not returned.
• expiry_date cannot be set when creating or updating a password.
• Locked passwords only return basic data (name, project).
• Locked passwords cannot be listed its users, updated or deleted. 403 forbidden is returned.