python-sdk

---

path: secret-management/python-sdk.mdx title: Gestión de secretos mediante Python SDK slug: /secret-management/python-sdk pagination_next: secret-management/rotation pagination_prev: secret-management/cli sidebar_position: 4 description: >- Uso de Passwork Python SDK para leer, actualizar y crear secretos, así como automatizar la rotación y migración de secretos. keywords:

• Passwork
• Python
• SDK
• secrets
• automation
• rotation

---

Qué es el Python SDK

El Python SDK es una biblioteca para la interacción programática con Passwork. Está diseñado para automatización avanzada donde las capacidades de CLI no son suficientes.

Funcionalidad	Descripción
Lectura de secretos	Obtener contraseñas, campos y archivos adjuntos por ID o búsqueda
Modificación de secretos	Actualizar contraseñas, campos, etiquetas y descripciones
Creación de secretos	Añadir registros programáticamente a carpetas específicas
Gestión de estructura	Trabajar con carpetas y bóvedas, mover registros

Cuándo usar SDK vs CLI

Escenario	Recomendación
Pipeline de CI/CD, script de despliegue	passwork-cli — más simple, no requiere código
Rotación de contraseñas con lógica personalizada	Python SDK — más flexibilidad, mejor manejo de errores
Migración desde otro sistema	Python SDK — transformar datos según sea necesario
Verificación de integridad de secretos	Python SDK — implementar validación compleja
Obtener un solo secreto en bash	passwork-cli get — solo un comando

Instalación

Instale con pip desde GitHub:

# PyPI
pip install passwork-python

# Or from GitHub via SSH
pip install git+ssh://[email protected]:passwork-me/passwork-python.git

# Or from GitHub via HTTPS
pip install git+https://github.com/passwork-me/passwork-python.git

Consulte también: Conector Python.

Inicialización del cliente

from passwork import Client

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

tip

Evite codificar tokens en su código. Utilice variables de entorno en su lugar:

import os
from passwork import Client

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

Lectura de secretos

Por ID de registro

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

# Standard fields
print(item.login)
print(item.password)

# Custom fields
db_host = item.fields["MYSQL_HOST"]
stripe_key = item.fields["STRIPE_SECRET"]

Por carpeta

# Fetch all records from a folder
items = client.list_folder_items(folder_id="<folder-id>")

for item in items:
    print(f"{item.title}: {item.login}")

Por cadena de búsqueda

# Find records matching a query
items = client.search("mysql production")

for item in items:
    print(f"{item.id}: {item.title}")

Modificación de secretos

Actualización de un registro existente

# Load the record
item = client.get_password(item_id="<item-id>")

# Change fields
item.password = "Jk8$mNp#2xLq!9Wz"
item.fields["STRIPE_SECRET"] = "sk_live_abc123xyz"

# Persist changes
client.update_password(item)

Creación de un nuevo registro

client.create_password(
    folder_id="<folder-id>",
    title="MySQL Primary",
    login="backend_svc",
    password="Tm4#kL9$pQ2!xZ7",
    fields={
        "MYSQL_HOST": "mysql.prod.internal",
        "MYSQL_PORT": "3306",
    },
    tags=["production", "db"],
)

Operaciones masivas

El SDK permite automatización como:

• mover registros entre carpetas;
• añadir o eliminar etiquetas de forma masiva;
• actualizar campos basándose en una plantilla;
• migrar la jerarquía secrets/*.

# Add a tag to all records in a folder
items = client.list_folder_items(folder_id="<folder-id>")

for item in items:
    if "legacy" not in item.tags:
        item.tags.append("legacy")
        client.update_password(item)

Ejemplos prácticos

Rotación de una contraseña de base de datos

Ejemplo completo con manejo de errores para la rotación de contraseñas de PostgreSQL:

import os
import secrets
import psycopg2
from passwork import Client

def rotate_db_password(item_id: str, db_user: str):
    """Rotate the password for a PostgreSQL user."""
    
    # Set up the client
    client = Client(
        url=os.environ["PASSWORK_HOST"],
        token=os.environ["PASSWORK_TOKEN"],
    )
    
    # Create a fresh password
    new_password = secrets.token_urlsafe(32)
    
    # Retrieve admin credentials for the DB connection
    admin_item = client.get_password(item_id=os.environ["PG_ADMIN_ITEM_ID"])
    
    try:
        # Apply the new password in PostgreSQL
        conn = psycopg2.connect(
            host=admin_item.fields["PG_HOST"],
            dbname="postgres",
            user=admin_item.login,
            password=admin_item.password,
        )
        conn.autocommit = True
        
        with conn.cursor() as cur:
            cur.execute(
                "ALTER ROLE %s WITH PASSWORD %s",
                (db_user, new_password)
            )
        
        conn.close()
        
        # Store the updated password in Passwork
        item = client.get_password(item_id=item_id)
        item.password = new_password
        client.update_password(item)
        
        print(f"Password rotated for {db_user}")
        return True
        
    except Exception as e:
        print(f"Rotation failed: {e}")
        return False

# Usage
rotate_db_password(
    item_id="<item-id>",
    db_user="order_service"
)

Verificación de validez de secretos

Script que verifica periódicamente que las credenciales almacenadas siguen funcionando:

import os
import psycopg2
from passwork import Client

def check_db_credentials(folder_id: str):
    """Verify that database credentials in Passwork are valid."""
    
    client = Client(
        url=os.environ["PASSWORK_HOST"],
        token=os.environ["PASSWORK_TOKEN"],
    )
    
    items = client.list_folder_items(folder_id=folder_id)
    broken = []
    
    for item in items:
        if "db" not in item.tags:
            continue
            
        try:
            conn = psycopg2.connect(
                host=item.fields.get("PG_HOST"),
                dbname=item.fields.get("PG_DATABASE", "postgres"),
                user=item.login,
                password=item.password,
                connect_timeout=5,
            )
            conn.close()
            print(f"[OK] {item.title}")
            
        except Exception as e:
            print(f"[FAIL] {item.title}: {e}")
            broken.append(item)
            
            # Flag the record for review
            if "stale" not in item.tags:
                item.tags.append("stale")
                client.update_password(item)
    
    return broken

# Usage
broken = check_db_credentials(folder_id="<infrastructure/production/databases>")
if broken:
    print(f"\n{len(broken)} secrets need review")

Importación de secretos desde archivos

Migre secretos desde archivos .env a Passwork:

import os
from pathlib import Path
from passwork import Client

def migrate_env_file(env_path: str, folder_id: str, tags: list):
    """Import secrets from a .env file into Passwork."""
    
    client = Client(
        url=os.environ["PASSWORK_HOST"],
        token=os.environ["PASSWORK_TOKEN"],
    )
    
    env_file = Path(env_path)
    secrets_dict = {}
    
    # Parse the .env file
    for line in env_file.read_text().splitlines():
        line = line.strip()
        if not line or line.startswith("#"):
            continue
        if "=" in line:
            key, value = line.split("=", 1)
            secrets_dict[key.strip()] = value.strip().strip('"\'')
    
    # Store in Passwork
    client.create_password(
        folder_id=folder_id,
        title=env_file.stem,
        fields=secrets_dict,
        tags=tags,
    )
    
    print(f"Imported {len(secrets_dict)} secrets from {env_path}")

# Usage
migrate_env_file(
    env_path="./legacy/.env.production",
    folder_id="<infrastructure/production/backend>",
    tags=["production", "imported"],
)