API overview

Passwork API provides a programmatic interface for interacting with the Passwork password management service. The API allows automating operations with passwords, vaults, users, and other system objects, providing full programmatic control over all aspects of working with Passwork.

Our API offers the following capabilities:

• Password management: creating, retrieving, updating, deleting passwords;
• Vault management: creating new vaults, managing access;
• Folder management: creating folder structures inside vaults;
• User management: creating users, setting access rights;
• User group management: grouping users to simplify access management;
• Shared access to passwords: granting other users access to passwords via the Inbox mechanism;
• Creating public links: temporary access to passwords via links;
• Attachment support: working with files attached to passwords;
• Search and filtering: searching passwords by various criteria;
• Shortcut management: creating links to passwords in other vaults;
• Trash management: restoring deleted objects;
• Activity logging: retrieving information about user actions.

When installing Passwork, the .zip archive also includes Api reference.pdf, containing detailed descriptions of all available API endpoints:

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

One of the key features of Passwork API is support for client-side encryption. When using client-side encryption, all critically important data (passwords, confidential fields, attachments) are encrypted on the client side before being sent to the server.

Cryptography principle

1. Master password: Encryption uses a master password known only to the user. The master password is never sent to the server;
2. Master key: Based on the master password, a master key is generated using PBKDF2 (Password-Based Key Derivation Function 2);
3. Master key hash: A hash of the master key is calculated using SHA-256. This hash is sent to the server to authenticate the client;
4. Vault keys: A unique key is generated for each vault, used to encrypt passwords and other data in that vault;
5. Asymmetric encryption: For key exchange between users, asymmetric encryption (RSA) is used. Each user has a key pair - public and private;
6. Data encryption: Symmetric AES encryption in CBC mode with PKCS7 padding is used to encrypt passwords and other confidential data.

API client responsibility

danger

Important: According to the Zero Knowledge architecture, Passwork API assumes cryptographic operations are performed on the client side. This means encryption and decryption of data must be done in the client application before sending to the server. The Passwork server works with already encrypted data and additionally applies its own encryption layer, creating multi-layer protection.

The API client must ensure:

• Generation and storage of the master key based on the master password;
• Encryption of data before sending to the server;
• Decryption of data received from the server;
• Calculation of the master key hash for authorization;
• Asymmetric encryption of keys when exchanging with other users.

Python connector

To simplify working with the API and implementing all necessary cryptographic operations, Passwork provides an official Python connector. The connector encapsulates all the complexity of working with cryptography and the API into a simple programmatic interface.

The Python connector provides:

• Session and authorization management;
• Automatic session renewal via refreshToken;
• Cryptographic operations (encryption/decryption);
• Ready-made methods for main API operations;
• A universal call() method for arbitrary API requests.

Authorization and session handling

Authorization

The authorization process is as follows:

1. The Passwork user on the Authorization and 2FA tab in the API tokens section clicks Generate pair;
2. The server returns a pair of tokens: accessToken and refreshToken;
3. The user uses the accessToken for all subsequent requests, adding it to the Authorization: Bearer {accessToken} header;
4. If client-side encryption is enabled, the user also receives Passwork-MasterKeyHash and adds it to the header.

Session handling and refreshToken

Passwork API uses access tokens with limited validity:

1. Access Token: The main token for authorizing requests. Has a limited lifetime (usually minutes or hours);
2. Refresh Token: A long-lived token used to obtain a new access token without re-authentication;
3. Token renewal: When the access token expires, the client receives a 401 error with code accessTokenExpired. 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;
4. Automatic renewal: The Python connector automatically handles token expiration and performs renewal without user intervention;
5. Session saving: The Python connector allows saving and restoring sessions, convenient for long-term automation. Saved sessions are encrypted for security.

Security recommendations

When using Passwork API, the following security recommendations should be observed:

1. Protect API keys: Store API keys securely, use environment variables or secure secret stores;
2. Key rotation: Regularly update API keys to minimize risks;
3. HTTPS: Use only HTTPS for all API communications;
4. Least privilege: Create separate API users with minimal necessary access rights;
5. Protect master password: Store the master password with maximum protection, as compromise of the master password leads to compromise of all passwords;
6. Protect saved sessions: Ensure reliable protection of saved sessions and encryption keys;
7. Error handling: Carefully handle API errors, avoiding disclosure of sensitive information in logs.

API endpoints and capabilities

Vaults

• Create vault: POST /api/v1/vaults
• Get list of vaults: GET /api/v1/vaults
• Get vault info: GET /api/v1/vaults/{id}
• Update vault: POST /api/v1/vaults/{id}
• Delete vault: DELETE /api/v1/vaults/{id}
• Manage user access:
  • POST /api/v1/vaults/{id}/grant-user-access
  • POST /api/v1/vaults/{id}/revoke-user-access
• Manage group access:
  • POST /api/v1/vaults/{id}/grant-user-group-access
  • POST /api/v1/vaults/{id}/revoke-user-group-access
• Import vaults: POST /api/v1/vaults/import

Folders

• Create folder: POST /api/v1/folders
• Get list of folders: GET /api/v1/folders
• Get folder info: GET /api/v1/folders/{id}
• Update folder: POST /api/v1/folders/{id}
• Delete folder: DELETE /api/v1/folders/{id}
• Copy folder: POST /api/v1/folders/{id}/copy
• Move folder: POST /api/v1/folders/{id}/move
• Manage access:
  • POST /api/v1/folders/{id}/grant-user-access
  • POST /api/v1/folders/{id}/revoke-user-access
• Import/export folders:
  • POST /api/v1/folders/import
  • POST /api/v1/directories/export

Items/Passwords

• Create password: POST /api/v1/items
• Get list of passwords: GET /api/v1/items
• Get password info: GET /api/v1/items/{id}
• Update password: PATCH /api/v1/items/{id}
• Delete password: DELETE /api/v1/items/{id}
• Copy password: POST /api/v1/items/{id}/copy
• Move password: POST /api/v1/items/{id}/move
• Get attachments: GET /api/v1/items/{id}/attachment/{attachmentId}
• Bulk operations:
  • POST /api/v1/items/copy/bulk
  • POST /api/v1/items/move/bulk
  • POST /api/v1/items/delete/bulk
• Import/export passwords:
  • POST /api/v1/items/import
  • POST /api/v1/items/export
• Search passwords: GET /api/v1/items/search
• Security analysis: GET /api/v1/items/security-analysis

Users

• Create user: POST /api/v1/users
• Get list of users: GET /api/v1/users
• Get user info: GET /api/v1/users/{id}
• Update user: PATCH /api/v1/users/{id}
• Delete user: DELETE /api/v1/users/{id}
• Block/unblock user:
  • POST /api/v1/users/{id}/block
  • POST /api/v1/users/{id}/unblock
• Two-factor authentication:
  • POST /api/v1/users/2fa/set-up
  • POST /api/v1/users/2fa/set-state
  • POST /api/v1/users/2fa/reset

User groups

• Create group: POST /api/v1/user-groups
• Get list of groups: GET /api/v1/user-groups
• Get group info: GET /api/v1/user-groups/{id}
• Update group: POST /api/v1/user-groups/{id}
• Delete group: DELETE /api/v1/user-groups/{id}
• Manage group members:
  • POST /api/v1/user-groups/{id}/add-users
  • POST /api/v1/user-groups/{id}/remove-users
• Bulk group operations:
  • POST /api/v1/user-groups/delete/bulk
  • POST /api/v1/user-groups/set-state/bulk

User roles

• Create role: POST /api/v1/user-roles
• Get list of roles: GET /api/v1/user-roles
• Get role info: GET /api/v1/user-roles/{id}
• Update role: PATCH /api/v1/user-roles/{id}
• Delete role: DELETE /api/v1/user-roles/{id}
• Manage permissions: GET /api/v1/user-roles/permission-items/list

Shared access (Inbox items)

• Send password to user: POST /api/v1/inbox-items/send-to-user
• Send password to user group: POST /api/v1/inbox-items/send-to-user-group
• Get list of inbox passwords: GET /api/v1/inbox-items
• Search inbox password: GET /api/v1/inbox-items/search
• Get inbox password: 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 link: POST /api/v1/links
• Get list of links:
  • GET /api/v1/links/folder/{folderId}
  • GET /api/v1/links/item/{itemId}
  • GET /api/v1/links/vault/{vaultId}
• Delete link: DELETE /api/v1/links/{id}
• Bulk delete: POST /api/v1/links/delete/bulk

Trash (Bin items)

• Get list of trash items: GET /api/v1/bin-items
• Get trash item:
  • GET /api/v1/bin-items/{id}/folder
  • GET /api/v1/bin-items/{id}/item
  • GET /api/v1/bin-items/{id}/shortcut
• Restore items:
  • POST /api/v1/bin-items/restore/bulk
  • POST /api/v1/bin-items/restore-and-move/bulk
• Delete items:
  • DELETE /api/v1/bin-items/{id}
  • POST /api/v1/bin-items/delete/bulk
  • DELETE /api/v1/bin-items/all

Shortcuts

• Create shortcut: POST /api/v1/shortcuts
• Get list of shortcuts: GET /api/v1/shortcuts
• Get shortcut info: GET /api/v1/shortcuts/{id}
• Copy shortcut: POST /api/v1/shortcuts/{id}/copy
• Move shortcut: POST /api/v1/shortcuts/move/bulk
• Delete shortcut: DELETE /api/v1/shortcuts/{id}
• Bulk operations:
  • POST /api/v1/shortcuts/create/bulk
  • POST /api/v1/shortcuts/copy/bulk
  • POST /api/v1/shortcuts/move/bulk
  • POST /api/v1/shortcuts/delete/bulk

Activity log

• Get logs: GET /api/v1/activity-logs
• Get event info: GET /api/v1/activity-logs/{id}
• Get recent user activities: GET /api/v1/activity-logs/directories/last-users-activities
• Get recent activity of a user: GET /api/v1/activity-logs/user/latest

Sessions

• Get current session info: GET /api/v1/sessions/current/info
• Get list of sessions: GET /api/v1/sessions
• Delete session: DELETE /api/v1/sessions/{id}
• Refresh token: POST /api/v1/sessions/refresh

Settings

• Get/update 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 logs: 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 invite: POST /api/v1/user-invites
• Get list of invites: GET /api/v1/user-invites
• Get invite info: GET /api/v1/user-invites/{id}
• Delete invite: DELETE /api/v1/user-invites/{id}
• Create and send invite: POST /api/v1/user-invites/create-and-send