Conector de Python

El conector de Python de Passwork envuelve la REST API y todas las operaciones criptográficas en una interfaz de Python de alto nivel. Utilícelo cuando necesite más control del que ofrece la CLI de Passwork: operaciones por lotes, lógica condicional, gestión de errores, migraciones o informes personalizados.

La clase principal es PassworkClient. Proporciona acceso a todos los objetos de Passwork —bóvedas, carpetas, elementos, usuarios, grupos, sesiones— y gestiona la renovación de tokens y el CSE de forma transparente.

---

Instalación

PyPI

pip install passwork-python

GitHub (SSH)

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

Requisitos:

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

---

Autenticación

Token pair (recommended)

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"),
)

With 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"],
)

Cuando se proporciona refresh_token, el conector renueva el token de acceso automáticamente al caducar. No se necesita gestión manual de tokens en los scripts de larga duración.

---

Lectura de secretos

Obtener un único elemento por ID

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)

Obtener todos los elementos de una carpeta

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

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

Acceder a los campos personalizados

Los campos personalizados están disponibles en el diccionario item.fields, indexados por el nombre del campo:

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")

Buscar en todas las bóvedas

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

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

---

El CSE y el MasterKeyManager

Cuando el cifrado del lado del cliente está activado, el componente MasterKeyManager gestiona la derivación de la clave a partir de la clave maestra, el descifrado de la clave privada RSA y el desenvolvimiento de las claves por bóveda y por elemento. El cliente gestiona esto automáticamente cuando se proporciona master_key.

Si necesita derivar la clave maestra a partir de una contraseña maestra (en lugar de proporcionar la clave ya derivada):

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,
)

En la práctica, la mayoría de la automatización utiliza la clave PASSWORK_MASTER_KEY ya derivada (que es una cadena de bytes codificada en base64) en lugar de la contraseña maestra sin procesar.

---

Escritura y actualización de secretos

Actualizar la contraseña de un elemento existente

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

Actualizar el valor de un campo personalizado

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

Crear un nuevo elemento

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)

---

Persistencia de sesiones

Para los scripts que se ejecutan con frecuencia, guarde y restaure la sesión para evitar generar un nuevo par de tokens en cada ejecución:

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)

Las sesiones guardadas están cifradas. La clave de cifrado se deriva de una combinación de material del token y no se almacena junto al archivo de sesión.

---

Gestión de errores

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}")

Códigos de error de la API habituales que conviene gestionar:

Código	Significado	Acción
accessTokenExpired	El token de acceso ha caducado	El conector lo gestiona automáticamente si se ha configurado el token de renovación
itemNotFound	El ID del elemento no existe	Verifique el ID del elemento o compruebe el acceso a la bóveda
forbidden	La cuenta de servicio no tiene permiso	Revise el nivel de acceso a la bóveda
masterKeyRequired	El CSE está activado pero no se ha proporcionado la clave maestra	Añada master_key al constructor Client()

---

Método universal call()

Para cualquier endpoint de la API no cubierto por un método específico del conector, utilice 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"]},
)

Para consultar la referencia completa de la API, consulte API e integraciones: descripción general.

Para ver más ejemplos del conector de Python, consulte el repositorio de ejemplos de integración.

LLM version