API: Change log

API v5

Changes in API security

Since v. 13.166.291:

• You can configure which authentication method is enabled for the API: both HTTP Basic and HMAC, HTTP Basic only, or HMAC only.
• You can set whether HMAC API keys will expire after a specified number of days or remain valid indefinitely.

Changes in API v5

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 and the "otp_value" field returned the OTP value.

Changes from API v4 to API v5

In projects

• List passwords of a project: new field: "has_password" (true/false) true=the password entry has the password datum.
• NEW: List files of a project: GET /projects/ID/files.json
• NEW: Upload a file to a project: POST /projects/ID/upload.json

In passwords

• List passwords: new fields:
  • "has_password" (true/false) true=the password entry has the password datum.
  • "linked" (true/false) true=the password is a linked password.
  • "project_archived" (true/false) true=the project of the password is archived.
  • "locking_type" 0=password not locked, 1=requires a reason to unlock, 2=requires permission to unlock.
• Show a password: new fields:
  • "linked" (true/false) true=the password is a linked password, and "source_password_id" (=0 or the id of the source password).
  • "project_archived" (true/false) true=the project of the password is archived.
  • "locking_type" 0=password not locked, 1=requires a reason to unlock, 2=requires permission to unlock.
  • "locking_request_notify" 0=password not locked, 1=notify/request the password manager, 2=notify/request all the users with manage permission.
  • Linked passwords now show the "created_by" and "created_on" data corresponding to when the link was created, not the source password.
  • Custom fields of type "One Time Password" return the secret key in the "data" field and the OTP value at the time of the request in the "otp_value" field.
• Show a password: security data (users_permissions and groups_permissions) are only available to users with manage permission on the password (they're set to null for users that don't have the manage permission).
• NEW: Archive/un-archive a password: PUT /passwords/ID/archive.json and PUT /passwords/ID/unarchive.json
• NEW: Move a password to another project: PUT /passwords/ID/move.json
• NEW: List files of a password: GET /passwords/ID/files.json
• NEW: Upload a file to a password: POST /passwords/ID/upload.json
• Update custom fields definitions of a password (PUT /passwords/ID/custom_fields.json): includes custom types "One Time Password" or "OTP" and "Date".
• List users who can access a password (GET /passwords/ID/security.json): this request is only available to the users who have manage permission on the password.

In my passwords

• List passwords: new field: "has_password" (true/false) true=the password entry has the password datum.
• NEW: Move a password to a project: PUT /my_passwords/ID/move.json

New: files

• List files of a password: GET /passwords/ID/files.json
• List files of a project: GET /projects/ID/files.json
• Show a file: GET /files/ID.json
• Update the notes a file: PUT /files/ID.json
• Max upload file size: GET /files/max_upload_file_size.json
• Uploads folder information: GET /files/uploads_folder_info.json
• Download a file: GET /files/download/ID.json
• Delete a file: DELETE /files/ID.json

In groups

• List groups: new field "is_ldap" (true/false).
• Show a group: new fields: "is_ldap" (true/false), "ldap_server_id" (0-9) and "group_dn".

In users

• List users: new fields "is_saml" (true/false), "is_api_only" (true/false), "last_login" and "last_api_request".
• Show a user: new fields: "is_saml" (true/false), "is_api_only" (true/false), "ldap_server_id" (0-9) and "can_create_project_in_root" (true/false).
• Create a user: now only used to create normal (not LDAP, not SAML) users. New field: "can_create_projects_in_root" (true/false).
• NEW: Create an LDAP user: POST /users_ldap.json
• NEW: Create a SAML user: POST /users_saml.json
• Update a user: new fields: "can_create_projects_in_root" (true/false) and "ldap_server_id" (1/9).
• Convert a normal user to LDAP user: now the "ldap_server_id" (1/9) must be specified.
• NEW: Convert a normal user to a SAML user: PUT /users/ID/convert_to_saml.json.

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.