FAQ and best practices

Security and architecture

What happens if I lose the master key?

Without the master key, decrypting secrets is impossible — a direct consequence of Zero-Knowledge architecture. The server doesn't store keys and cannot assist with recovery.

What to do:

• For service accounts, store the master key in protected CI variables and a separate secure location (a safe or HSM).
• For users, ensure your administrator can reset the password and grant fresh vault access.

What can the Passwork server administrator see?

An administrator managing Passwork infrastructure can view:

Visible	Not visible
Vault and folder structure	Decrypted passwords
Record names	Field values
Metadata (tags, dates)	Attachment contents
Audit log	User encryption keys

Even with full server and database access, the administrator cannot read secrets.

Can Zero-Knowledge be disabled?

Yes. In the on-premise version, an administrator can disable Zero-Knowledge mode. This simplifies certain scenarios (like access recovery) but lowers overall security. Confirm your setup with your security team.

What to do if a CI token is leaked?

1. Revoke the token immediately — from the service account settings.
2. Review the audit log — identify what operations the token performed.
3. Rotate affected secrets — any secret the compromised account could access.
4. Issue a new token — update it in your CI system.

tip

Use separate service accounts per CI pipeline. That way, leaking one token doesn't expose everything.

Working with CLI and SDK

Why does CLI need both an access token and a master key?

• Access token — authenticates you with the Passwork API.
• Master key — decrypts data locally (Zero-Knowledge).

Without the access token, you can't retrieve encrypted data. Without the master key, you can't decrypt it.

How does CLI fetch data?

When you run passwork-cli, it:

1. Authenticates with the server.
2. Downloads encrypted records from the specified folder.
3. Decrypts them locally.
4. Injects values into environment variables or writes them to STDOUT.

There's no caching between calls — each invocation fetches fresh data from the server.

How are update conflicts handled?

Passwork uses optimistic locking. When two clients update the same record simultaneously:

1. The first one succeeds.
2. The second receives a conflict error.
3. The second client must re-fetch the record and retry.

In Python SDK:

try:
    client.update_password(item)
except ConflictError:
    # Reload and try again
    item = client.get_password(item_id=item.id)
    item.password = new_password
    client.update_password(item)

Can I use CLI without Docker?

Absolutely. passwork-cli is a Python package you can install via pip:

pip install passwork-python

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

Docker is convenient for CI/CD when you don't want to manage a Python environment.

Organizing secrets

How should I structure folders for multiple teams?

An example for an organization with several products:

infrastructure/
├── shared/             # Shared infrastructure
│   ├── production/
│   └── staging/
├── orders-team/        # Orders service team
│   ├── production/
│   ├── staging/
│   └── development/
└── payments-team/      # Payments service team
    ├── production/
    └── staging/

Access rights:

• Orders team → orders-team/* only
• Payments team → payments-team/* only
• Platform engineers → all folders
• CI/CD service accounts → read-only to specific folders

How should I name records for automation?

Use predictable, descriptive names:

# Good — purpose is obvious
mysql-orders-prod
elasticsearch-logs
sendgrid-api-key

# Avoid — requires opening to understand
creds-1
temp-secret
abc123

When using exec with a folder, record names become environment variable names. Stick to UPPER_SNAKE_CASE:

MYSQL_PASSWORD
ELASTIC_AUTH
SENDGRID_API_KEY

Should I store multiple related secrets in one record?

Yes, when secrets are logically related and used together:

Record: mysql-orders-prod
├── login: order_service
├── password: ...
├── MYSQL_HOST: mysql.prod.internal
├── MYSQL_PORT: 3306
└── MYSQL_DATABASE: orders

No, when secrets are independent or rotate on different schedules.

Rotation and lifecycle

Why doesn't Passwork rotate secrets automatically?

Zero-Knowledge means the server cannot access decrypted data. Rotation requires:

1. Decrypting the current value (needs client keys).
2. Generating a new one.
3. Updating the target system (database, service).
4. Encrypting and storing the new value.

Steps 1, 3, and 4 require a client with keys and access to the target. The server doesn't have that.

Can I recover a deleted secret?

Recovery depends on server settings (recycle bin, soft delete). Check with your administrator.

warning

Always back up before bulk operations and test scripts in a staging environment first.

Migration and integration

How do I migrate from another secrets manager?

General approach:

1. Export secrets from the old system (typically JSON or YAML).
2. Write a script to transform data into Passwork's structure.
3. Import via Python SDK (create_password).

See the Python SDK section for a .env migration example.

How do I integrate Passwork with Terraform?

There's no official Terraform provider, but you can:

1. Use an external data source with passwork-cli get.
2. Write a wrapper script that reads secrets and passes them to Terraform.

data "external" "db_password" {
  program = ["bash", "-c", "passwork-cli get --password-id $ID --json"]
}

resource "aws_db_instance" "main" {
  password = data.external.db_password.result.password
}

LLM version