Python connector

Overview

Passwork Python Connector is a tool that simplifies integration of Passwork with company infrastructure for programmers and DevOps engineers. The connector allows quick and secure automation of working with passwords, vaults, and accesses without diving into low-level API interaction and cryptography details.

Main tasks and advantages

• Simplifying integration: The connector eliminates the need to manually implement API handling, encryption, and sessions. All main operations are reduced to simple methods.
• Client-side security: All client-side cryptography (encryption, decryption, working with the master key) is implemented inside the connector. Your secrets are always protected — even when working with an open API.
• Session management: The connector allows saving and restoring sessions to avoid re-authentication on every script run.
• Flexibility: For all API methods not covered by specific connector functions, a universal call method is implemented. It allows accessing any Passwork API endpoints while maintaining security and ease of use.

Requirements

• Python 3.10+
• requests>=2.31.0
• python-dotenv>=1.0.0
• cryptography>=42.0.0
• pbkdf2>=1.3

Installation

You can install the package directly from Github:

shell

pip install git+ssh://[email protected]:passwork-me/passwork-python.git

Or via HTTPS:

shell

pip install git+https://github.com/passwork-me/passwork-python.git

Features

• Client-side encryption with master password support;
• Automatic token refresh;
• Encrypted storage and restoration of sessions;
• Multi-level encryption (PBKDF2, RSA, AES);
• Handling attachments;
• User and role management;
• Vault management;
• Password sharing via "incoming";
• Support for custom fields;
• Tagging system;

Advanced usage

Passwork version 7 uses a token mechanism with limited lifetime:

1. Access Token: The main token for request authorization. Has a limited lifetime (usually several minutes or hours);
2. Refresh Token: Long-lived token used to obtain a new access token without re-authentication;

Session management

The connector can save and use tokens and, in case of ACCESS_TOKEN expiration, automatically refresh tokens (if REFRESH_TOKEN is set):

Python

# Enable usage and automatic token refresh during authorization
passwork = PassworkClient(HOST, True, True)

# Load and decrypt tokens from session.file for use in the current script
passwork.load_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=")

# Save tokens from the current script to session.file in encrypted form
encryption_key = passwork.save_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=", True)

Example script with automatic token refresh:

Python

import sys
import os
from passwork_client import PassworkClient

# Configuration
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Optional (required for token refresh)
MASTER_KEY = "" # Master key (if client-side encryption is enabled)
HOST = "https://passwork" # Passwork address

# Authorization in Passwork
try:
    # Enable usage and automatic token refresh during authorization
    passwork = PassworkClient(HOST, True, True)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}")
    exit(1)

# Load and decrypt tokens from session.file for use in the current script
#passwork.load_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=")

# Example: Create a vault
try:
    vault_name = "Python Vault"
    vault_id = passwork.create_vault(vault_name)
    print(f"Vault was created: {vault_id}")
except Exception as e:
    print(f"Error: {e}")

# Save tokens from the current script to session.file in encrypted form 
encryption_key = passwork.save_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=", True)

On first run, loading tokens from the session.file should be commented out — since tokens are not saved yet. On subsequent runs, uncomment the line to use previously saved tokens:

Python

passwork.load_session("session.file", "P2eYN+VtHH27Hno2plpWwoxFOZ0uFNLzubdEcLUPCSU=")

Password management

Creating a password with custom fields, tags, and attachments:

Python

import sys
import os
from passwork_client import PassworkClient

# Configuration
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Optional (required for token refresh)
MASTER_KEY = "" # Master key (if client-side encryption is enabled)
HOST = "https://passwork" # Passwork address

# Authorization in Passwork
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}") 
    exit(1)

# Example: Create an item
try:
    VAULT_ID = ""
    COLOR = 8
    
    # Example additional fields
    custom_fields = [
        {
            "name": "Text Field",
            "value": "Field value",
            "type": "text"
        },
        {
            "name": "Custom Password",
            "value": "Secret123!",
            "type": "password"
        },
        {
            "name": "TOTP",
            "value": "ABCDEFGHIJKLMNOP",
            "type": "totp"
        }
    ]
    
    # Prepare item data
    item_data = {
        "vaultId": VAULT_ID,
        "name": "New Item",
        "login": "test_user",
        "password": "Test_password123!",
        "url": "https://example.com",
        "description": "Item description",
        "color": COLOR,
        "tags": ["tag1", "tag2"],
        "customs": custom_fields
    }
    
    # Create item
    item_id = passwork.create_item(item_data)
    print(f"Item created with ID: {item_id}")
    
    # Get created item data
    item = passwork.get_item(item_id)
    print(f"Created item: {item}")

except Exception as e:
    print(f"Error: {e}") 

Updating an existing password:

Python

import sys
import os
from passwork_client import PassworkClient

# Configuration
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Optional (required for token refresh)
MASTER_KEY = "" # Master key (if client-side encryption is enabled)
HOST = "https://passwork" # Passwork address

# Authorization in Passwork
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}") 
    exit(1)

# Example: Update an item
try:
    # ID of the item to update
    ITEM_ID = ""
    VAULT_ID = ""
    
    # Get current item
    item = passwork.get_item(ITEM_ID)
    print(f"Current item: {item}")
    
    # Data to update the item
    updated_data = {
        "vaultId": VAULT_ID,
        "name": "Updated Item Name",
        "login": "updated_user",
        "password": "Updated_Password_456!",
        "url": "https://updated-example.com",
        "description": "Updated description",
        "tags": ["updated", "tag2", "tag3"],
        "customs": [
            {
                "name": "Updated Custom Field",
                "value": "Updated value",
                "type": "text"
            },
            {
                "name": "Updated Password Field",
                "value": "NewSecret456!",
                "type": "password"
            }
        ]
    }
    
    # Update item
    passwork.update_item(ITEM_ID, updated_data)
    
    # Get updated item
    updated_item = passwork.get_item(ITEM_ID)
    print(f"Updated item: {updated_item}")

except Exception as e:
    print(f"Error: {e}") 

Deleting a password:

Python

import sys
import os
from passwork_client import PassworkClient

# Configuration
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Optional (required for token refresh)
MASTER_KEY = "" # Master key (if client-side encryption is enabled)
HOST = "https://passwork" # Passwork address

# Authorization in Passwork
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}")
    exit(1)

# Example: Delete an item
try:
    # ID of the item to delete
    ITEM_ID = ""
    
    # Delete item
    bin_item_id = passwork.delete_item(ITEM_ID)
    print(f"Item deleted. Bin item ID: {bin_item_id}")
    
except Exception as e:
    print(f"Error: {e}")

User management

Creating a new user:

Python

import sys
import os
from passwork_client import PassworkClient

# Configuration
ACCESS_TOKEN = ""
REFRESH_TOKEN = "" # Optional (required for token refresh)
MASTER_KEY = "" # Master key (if client-side encryption is enabled)
HOST = "https://passwork" # Passwork address

# Authorization in Passwork
try:
    passwork = PassworkClient(HOST)
    passwork.set_tokens(ACCESS_TOKEN, REFRESH_TOKEN)
    if bool(MASTER_KEY):
        passwork.set_master_key(MASTER_KEY)
except Exception as e:
    print(f"Error: {e}") 
    exit(1)


# Example: Create a user
try:
    # Get available user roles
    roles_response = passwork.call("GET", "/api/v1/user-roles", {"includeUserRole": '1', "isOnlyManageable": '1'})
    if not roles_response or not roles_response.get("items"):
        print("Error: Could not fetch user roles or no manageable roles found.")
        exit(1)

    # Find "Employee" role (change if necessary)
    user_role_items = [r for r in roles_response["items"] if r.get("code") == "user"]
    if not user_role_items:
        print("Error: Default 'user' role not found.")
        exit(1)
    default_user_role_id = user_role_items[0]["id"]
    
    # Define user data
    user_data = {
        "email": "[email protected]",
        "fullName": "Python Test User",
        "login": "python_test_user",
        "userRoleId": default_user_role_id,
    }
    
    # Create user
    new_user = passwork.create_user(user_data)

    # Success message
    message = f"User '{user_data['fullName']}' created with ID: {new_user['user_id']}"
    if 'password' in new_user and new_user['password']:
         message += f", password: {new_user['password']}"
    if 'master_password' in new_user and new_user['master_password']:
        message += f", master password: {new_user['master_password']}"

    print(message)

except Exception as e:
    print(f"Error: {e}") 

Direct API calls

For operations not covered by helper methods:

Python

# Direct API call
response = client.call("DELETE", f"/api/v1/folders/{folder_id}")

Documentation

Detailed examples are located in the examples directory of the repository.