Python-Connector

Der Passwork-Python-Connector kapselt die REST API und alle kryptografischen Operationen in einer Python-Schnittstelle auf hoher Ebene. Verwenden Sie ihn, wenn Sie mehr Kontrolle benötigen, als die Passwork CLI bietet: Batch-Operationen, bedingte Logik, Fehlerbehandlung, Migrationen oder individuelles Reporting.

Die zentrale Klasse ist PassworkClient. Sie bietet Zugriff auf alle Passwork-Objekte — Tresore, Ordner, Elemente, Benutzer, Gruppen, Sitzungen — und verarbeitet die Token-Erneuerung und CSE transparent.

---

Installation

PyPI

pip install passwork-python

GitHub (SSH)

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

Voraussetzungen:

• Python 3.10+,
• requests>=2.31.0
• cryptography>=42.0.
• pbkdf2>=1.3

---

Authentifizierung

Token-Paar (empfohlen)

import os
from passwork import Client

client = Client(
    url=os.environ["PASSWORK_HOST"],
    token=os.environ["PASSWORK_TOKEN"],
    refresh_token=os.environ.get("PASSWORK_REFRESH_TOKEN"),
)

Mit CSE (Master Key)

import os
from passwork import Client

client = Client(
    url=os.environ["PASSWORK_HOST"],
    token=os.environ["PASSWORK_TOKEN"],
    refresh_token=os.environ.get("PASSWORK_REFRESH_TOKEN"),
    master_key=os.environ["PASSWORK_MASTER_KEY"],
)

Wenn refresh_token bereitgestellt wird, erneuert der Connector den Access-Token bei Ablauf automatisch. In langlaufenden Skripten ist keine manuelle Token-Verwaltung erforderlich.

---

Secrets lesen

Ein einzelnes Element per ID abrufen

item = client.get_password(item_id="<item_id>")

print(item.name)      # item name
print(item.login)     # login field
print(item.password)  # password field (decrypted if CSE enabled)

Alle Elemente aus einem Ordner abrufen

items = client.get_passwords(folder_id="<folder_id>")

for item in items:
    print(f"{item.name}: {item.password}")

Auf benutzerdefinierte Felder zugreifen

Benutzerdefinierte Felder sind im Dictionary item.fields verfügbar, indexiert nach Feldname:

item = client.get_password(item_id="<item_id>")

aws_key_id     = item.login
aws_secret_key = item.fields.get("AWS_SECRET_ACCESS_KEY")
aws_region     = item.fields.get("AWS_REGION")

Tresorübergreifend suchen

results = client.search_passwords(query="postgres")

for item in results:
    print(f"{item.name} in vault {item.vault_id}")

---

CSE und der MasterKeyManager

Wenn die client-seitige Verschlüsselung aktiviert ist, übernimmt die Komponente MasterKeyManager die Schlüsselableitung aus dem Master Key, die Entschlüsselung des privaten RSA-Schlüssels sowie das Entpacken der Schlüssel pro Tresor und pro Element. Der Client erledigt dies automatisch, wenn master_key bereitgestellt wird.

Falls Sie den Master Key aus einem Masterpasswort ableiten müssen (anstatt den vorab abgeleiteten Schlüssel bereitzustellen):

from passwork import Client
from passwork.crypto import MasterKeyManager

manager = MasterKeyManager()
master_key = manager.derive_master_key(
    password="your_master_password",
    salt="<salt_from_user_profile>",
)

client = Client(
    url="https://passwork.example.com",
    token="<token>",
    master_key=master_key,
)

In der Praxis verwendet die meiste Automatisierung den vorab abgeleiteten PASSWORK_MASTER_KEY (einen base64-kodierten Byte-String) anstelle des rohen Masterpassworts.

---

Secrets schreiben und aktualisieren

Das Passwort eines bestehenden Elements aktualisieren

item = client.get_password(item_id="<item_id>")
item.password = "new_strong_password_here"
client.update_password(item)

Den Wert eines benutzerdefinierten Feldes aktualisieren

item = client.get_password(item_id="<item_id>")
item.fields["AWS_SECRET_ACCESS_KEY"] = "new_aws_secret_key"
client.update_password(item)

Ein neues Element erstellen

from passwork.models import PasswordItem

new_item = PasswordItem(
    name="Redis sessions",
    login="redis",
    password="generated_password",
    folder_id="<target_folder_id>",
    tags=["production", "messaging"],
)
client.create_password(new_item)

---

Sitzungspersistenz

Speichern und stellen Sie bei häufig laufenden Skripten die Sitzung wieder her, um zu vermeiden, dass bei jedem Lauf ein neues Token-Paar generiert wird:

import os
from passwork import Client

session_file = "/tmp/passwork_session.enc"

client = Client(url=os.environ["PASSWORK_HOST"])

if os.path.exists(session_file):
    client.load_session(session_file)
else:
    client.set_tokens(
        token=os.environ["PASSWORK_TOKEN"],
        refresh_token=os.environ["PASSWORK_REFRESH_TOKEN"],
    )

# ... use client ...

client.save_session(session_file)

Gespeicherte Sitzungen sind verschlüsselt. Der Verschlüsselungsschlüssel wird aus einer Kombination von Token-Material abgeleitet und nicht zusammen mit der Sitzungsdatei gespeichert.

---

Fehlerbehandlung

from passwork import Client
from passwork.exceptions import PassworkResponseError, PassworkError

try:
    item = client.get_password(item_id="<item_id>")
except PassworkResponseError as e:
    # HTTP error from the Passwork API (4xx, 5xx)
    print(f"API error {e.code}: {e.message}")
except PassworkError as e:
    # Client-side error (network, encryption, etc.)
    print(f"Client error: {e}")

Häufige zu behandelnde API-Fehlercodes:

Code	Bedeutung	Aktion
accessTokenExpired	Access-Token abgelaufen	Connector erledigt dies automatisch, wenn ein Refresh-Token gesetzt ist
itemNotFound	Element-ID existiert nicht	Element-ID verifizieren oder Tresorzugriff prüfen
forbidden	Service-Account fehlt die Berechtigung	Zugangslevel des Tresors überprüfen
masterKeyRequired	CSE aktiviert, aber kein Master Key bereitgestellt	master_key zum Konstruktor Client() hinzufügen

---

Universelle call()-Methode

Für jeden API-Endpunkt, der nicht von einer spezifischen Connector-Methode abgedeckt wird, verwenden Sie call():

# Get activity logs
response = client.call(
    method="GET",
    endpoint="/api/v1/activity-logs",
    params={"limit": 100},
)

# Bulk delete items
response = client.call(
    method="POST",
    endpoint="/api/v1/items/delete/bulk",
    json={"ids": ["id1", "id2", "id3"]},
)

Die vollständige API-Referenz finden Sie unter API und Integrationen: Überblick.

Weitere Beispiele zum Python-Connector finden Sie im Repository mit Integrationsbeispielen.

LLM version