API & integrations

general overview of the api the passwork api provides a programmatic interface for interacting with the passwork password management service it enables the automation of operations with passwords, vaults, users, and other system entities, allowing full programmatic control over all aspects of working with passwork key features the passwork api offers the following capabilities password management create, retrieve, update, and delete passwords; vault management create new vaults, manage access; folder management create folder structures within vaults; user management create users, configure access rights; user group management group users to simplify access control; shared access provide password access to other users via the inbox mechanism; public links grant temporary password access via shareable links; attachment support work with files attached to passwords; search and filtering search for passwords based on various criteria; shortcut management create password shortcuts across vaults; trash bin operations recover deleted items; activity logging access information about user actions an api reference pdf file containing detailed descriptions of all available api endpoints is included with the passwork installation in the zip archive docker /\<passwork>/www/latest/files/api schema/api reference pdf windows server c \inetpub\wwwroot\passwork\files\api schema\api reference pdf linux /var/www/files/api schema/api reference pdf client side encryption a key feature of the passwork api is support for client side encryption all sensitive data (passwords, confidential fields, attachments) is encrypted on the client side before being sent to the server cryptographic principles master password encryption is based on a master password known only to the user it is never transmitted to the server; master key derived from the master password using pbkdf2 (password based key derivation function 2); master key hash a sha 256 hash of the master key is calculated and sent to the server to verify client authenticity; vault keys a unique key is generated for each vault and used for encrypting passwords and other data within that vault; asymmetric encryption used for sharing vault keys between users (rsa) each user has a public and private key pair; data encryption aes encryption in cbc mode with pkcs7 padding is used to encrypt passwords and other sensitive data client responsibility in accordance with zero knowledge architecture, passwork's api requires the implementation of cryptographic operations on the client side this means that data encryption and decryption must be performed in the client application before sending to the server the server side of passwork works with already encrypted data and additionally applies its own encryption layer, creating multi layered protection the api client must handle generating and securely storing the master key based on the master password; encrypting data before transmission to the server; decrypting data received from the server; calculating the master key hash for authorization; using asymmetric encryption for key exchange with other users python connector to simplify api usage and implement all necessary cryptographic operations, passwork provides an official python connector docid 5hcwgjv6jkmlm9zsuarye this connector encapsulates the complexities of cryptography and api interaction into a simple programming interface the python connector offers session and authorization management; automatic session renewal via refreshtoken ; cryptographic operations (encryption/decryption); prebuilt methods for core api operations; a universal call() method for custom api requests authorization and session handling authorization process in the authorization and 2fa section under api tokens , the user clicks generate pair ; the server returns a pair of tokens accesstoken and refreshtoken ; the accesstoken is used in all subsequent requests via the authorization bearer {accesstoken} header; if client side encryption is enabled, passwork masterkeyhash is also required in the header session and refresh token management access token the main token used for request authorization it has a limited lifetime (usually minutes or hours); refresh token a long lived token used to obtain a new access token without re authentication; token renewal when the access token expires, the client receives a 401 error with the accesstokenexpired code in this case, the client must send a request to the /api/v1/sessions/refresh endpoint with the current refresh token to get a new token pair; automatic renewal the python connector automatically handles token expiration and performs renewal without user intervention; session saving the python connector allows you to save and restore sessions, which is useful for long term automation saved sessions are encrypted for security security best practices protect api keys store api keys in a secure location, use environment variables or secure secret repositories; key rotation update api keys regularly to minimize risks; https use only https for all communications with the api; minimum privileges create separate users for the api with the minimum required access rights; master password protection store the master password with maximum protection, as compromising the master password will compromise all passwords; stored session protection ensure that stored sessions and encryption keys are securely protected; error handling handle api errors carefully without disclosing sensitive information in logs api endpoints and features vaults create post /api/v1/vaults list get /api/v1/vaults get info get /api/v1/vaults/{id} update post /api/v1/vaults/{id} delete delete /api/v1/vaults/{id} user access grant post /api/v1/vaults/{id}/grant user access revoke post /api/v1/vaults/{id}/revoke user access group access grant post /api/v1/vaults/{id}/grant user group access revoke post /api/v1/vaults/{id}/revoke user group access import post /api/v1/vaults/import folders create post /api/v1/folders list get /api/v1/folders get info get /api/v1/folders/{id} update post /api/v1/folders/{id} delete delete /api/v1/folders/{id} copy post /api/v1/folders/{id}/copy move post /api/v1/folders/{id}/move access grant post /api/v1/folders/{id}/grant user access revoke post /api/v1/folders/{id}/revoke user access import/export import post /api/v1/folders/import export post /api/v1/directories/export items (passwords) create post /api/v1/items list get /api/v1/items get info get /api/v1/items/{id} update patch /api/v1/items/{id} delete delete /api/v1/items/{id} copy post /api/v1/items/{id}/copy move post /api/v1/items/{id}/move get attachment get /api/v1/items/{id}/attachment/{attachmentid} bulk operations copy post /api/v1/items/copy/bulk move post /api/v1/items/move/bulk delete post /api/v1/items/delete/bulk import/export import post /api/v1/items/import export post /api/v1/items/export search get /api/v1/items/search security analysis get /api/v1/items/security analysis users create post /api/v1/users list get /api/v1/users get info get /api/v1/users/{id} update patch /api/v1/users/{id} delete delete /api/v1/users/{id} block/unblock block post /api/v1/users/{id}/block unblock post /api/v1/users/{id}/unblock master key change post /api/v1/users/master key/change reset post /api/v1/users/{id}/master key/reset 2fa set up post /api/v1/users/2fa/set up set state post /api/v1/users/2fa/set state reset post /api/v1/users/2fa/reset user groups create post /api/v1/user groups list get /api/v1/user groups get info get /api/v1/user groups/{id} update post /api/v1/user groups/{id} delete delete /api/v1/user groups/{id} manage members add users post /api/v1/user groups/{id}/add users remove users post /api/v1/user groups/{id}/remove users bulk operations delete post /api/v1/user groups/delete/bulk set state post /api/v1/user groups/set state/bulk user roles create post /api/v1/user roles list get /api/v1/user roles get info get /api/v1/user roles/{id} update patch /api/v1/user roles/{id} delete delete /api/v1/user roles/{id} permissions get /api/v1/user roles/permission items/list inbox items (shared access) send password post /api/v1/inbox items/send to user send password group post /api/v1/inbox items/send to user group list inbox items get /api/v1/inbox items get item get /api/v1/inbox items/{id} set access type post /api/v1/inbox items/{id}/set access bulk delete post /api/v1/inbox items/delete/bulk public links create post /api/v1/links list by folder get /api/v1/links/folder/{folderid} list by item get /api/v1/links/item/{itemid} list by vault get /api/v1/links/vault/{vaultid} delete delete /api/v1/links/{id} bulk delete post /api/v1/links/delete/bulk bin items list get /api/v1/bin items get item folder get /api/v1/bin items/{id}/folder item get /api/v1/bin items/{id}/item shortcut get /api/v1/bin items/{id}/shortcut restore bulk restore post /api/v1/bin items/restore/bulk restore and move post /api/v1/bin items/restore and move/bulk delete single item delete /api/v1/bin items/{id} bulk delete post /api/v1/bin items/delete/bulk delete all delete /api/v1/bin items/all shortcuts create post /api/v1/shortcuts list get /api/v1/shortcuts get info get /api/v1/shortcuts/{id} copy post /api/v1/shortcuts/{id}/copy move post /api/v1/shortcuts/{id}/move/bulk delete delete /api/v1/shortcuts/{id} bulk operations create post /api/v1/shortcuts/create/bulk copy post /api/v1/shortcuts/copy/bulk move post /api/v1/shortcuts/move/bulk delete post /api/v1/shortcuts/delete/bulk activity logs list get /api/v1/activity logs get event info get /api/v1/activity logs/{id} recent user activities get /api/v1/activity logs/directories/last users activities user latest actions get /api/v1/activity logs/user/latest sessions current session info get /api/v1/sessions/current/info list sessions get /api/v1/sessions delete session delete /api/v1/sessions/{id} refresh token post /api/v1/sessions/refresh settings passwords get/patch /api/v1/settings/auth password complexity master passwords get/patch /api/v1/settings/master password complexity interface get/patch /api/v1/settings/interface sessions get/patch /api/v1/settings/session notifications get/patch /api/v1/settings/notifications activity log get/patch /api/v1/settings/activity log search get/patch /api/v1/settings/search vaults get/patch /api/v1/settings/vault users get/patch /api/v1/settings/user user invites create post /api/v1/user invites list get /api/v1/user invites get info get /api/v1/user invites/{id} delete delete /api/v1/user invites/{id} create and send post /api/v1/user invites/create and send