Vault structure for DevOps

Why structure matters for automation

When a human uses Passwork, they can search by name and navigate visually. Automation cannot. A CI/CD pipeline or script needs to retrieve secrets by a predictable identifier — a folder ID or vault ID — and expects all required secrets to be in that location.

A well-designed structure means:

• A single --folder-id fetches all secrets a pipeline needs, with no manual assembly
• Adding a new secret to a pipeline requires adding a record to the right folder — not changing code
• Access control maps cleanly to team boundaries

---

Recommended hierarchy

Organize infrastructure secrets by environment first, then by service type:

Infrastructure (vault)
├── production/
│   ├── databases/
│   │   ├── postgres-order-service
│   │   ├── postgres-analytics
│   │   └── redis-sessions
│   ├── cloud/
│   │   ├── aws-credentials
│   │   └── gcp-service-account
│   ├── message-brokers/
│   │   └── rabbitmq-backend
│   └── external-apis/
│       ├── stripe-secret-key
│       └── twilio-auth-token
├── staging/
│   ├── databases/
│   ├── cloud/
│   └── external-apis/
└── development/
    ├── databases/
    └── local/

This layout means:

• A production deploy pipeline uses --folder-id <production folder ID> to get all production secrets
• Access control is per-environment: the svc-deploy-staging account has Read Only access to staging/, not production/
• A developer's laptop script uses --folder-id <development folder ID> without touching production

---

Naming conventions

Use names that are descriptive and machine-recognizable. When passwork-cli exec injects secrets into environment variables, it uses the item name (and custom field names) as the variable name, normalizing spaces and special characters to underscores.

Item name	Injected variable
POSTGRES_PASSWORD	POSTGRES_PASSWORD
postgres order service	POSTGRES_ORDER_SERVICE
AWS_SECRET_ACCESS_KEY	AWS_SECRET_ACCESS_KEY
Stripe Secret Key	STRIPE_SECRET_KEY

Recommended pattern: use SCREAMING_SNAKE_CASE for infrastructure items that are injected as environment variables. This makes the mapping explicit and avoids surprises.

---

What to put in which field

Passwork password records have several fields. Use them intentionally:

Field	What to store
Login	Username, service account name, key ID (e.g. AKIAIOSFODNN7EXAMPLE)
Password	The primary secret value (password, token, private key)
URL	Service endpoint or console URL (useful for human reference)
Custom fields	Named additional secrets: AWS_SECRET_ACCESS_KEY, DB_HOST, DB_PORT, connection strings
Description	Configuration notes, rotation procedure, owner team
Tags	Environment, service type (production, k8s, db)

Multi-secret records

When a service needs several related credentials, store them in one record using custom fields:

Record: "AWS production credentials"
  Login:     AKIAIOSFODNN7EXAMPLE
  Password:  wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
  Custom fields:
    AWS_REGION:      eu-central-1
    S3_BUCKET:       company-backups-prod
    ROLE_ARN:        arn:aws:iam::123456789:role/deploy-role

passwork-cli exec --password-id <id> will inject all of these as separate environment variables.

Storing SSH keys and certificates

For multi-line secrets (SSH private keys, TLS certificates, kubeconfig files), use a custom field with the full content. The CLI handles multi-line values correctly. Alternatively, use attachments for binary files.

TOTP codes

If a service account requires 2FA, Passwork can generate TOTP codes. Add a custom field of type TOTP and paste the authenticator seed. The CLI and Python SDK can retrieve the current TOTP code programmatically.

---

Tags for environment filtering

Apply tags to every infrastructure record:

• Environment tag: production, staging, development
• Service type tag: db, cloud, k8s, messaging, external-api
• Status tag: active, deprecated, rotation-pending

passwork-cli exec --tags "production,db" retrieves all records matching both tags. This is useful for scripts that operate across multiple services of the same type.

---

CSE considerations

When client-side encryption is enabled:

• The password field and custom field values are encrypted on the client before storage
• The item name, login, URL, tags, and description are NOT encrypted on the client — they are searchable on the server

This means you should not put sensitive data in the item name, description, or tags. Keep secrets in the password and custom fields.

The CLI and Python SDK handle CSE transparently when PASSWORK_MASTER_KEY is set. No code changes are needed when switching between CSE-enabled and CSE-disabled Passwork instances — only the presence or absence of the master key parameter changes.

---

Separating infrastructure vaults from business vaults

Keep infrastructure secrets in a dedicated vault (e.g. Infrastructure or DevOps). Do not mix them with business credentials (CRM logins, marketing tools). This makes:

• Access control cleaner: give CI/CD service accounts access only to the infrastructure vault
• Security reviews simpler: the security team knows exactly where to look for privileged credentials
• Rotation scope clearer: infrastructure rotation scripts operate on a known vault

For secret management best practices, see Secret management: concepts.

LLM version