Core concepts

Secret as a record in Passwork

Passwork doesn't have a dedicated "secret" entity — any password record can function as a secret. This gives you flexibility: the same interface works for both end-user passwords and infrastructure secrets.

Where to store a secret within a record

Field type	What to store	Example
Login	Username credentials	svc_backend
Password	Secrets, passwords, keys	xK9#mP2$vL7!nQ
Custom fields	Named secrets, tokens, keys	AWS_SECRET_KEY, OAUTH_CLIENT_SECRET, REDIS_AUTH
Description	Configuration snippets, JSON, YAML	Connection strings, JSON configs

Recommendation

For automation, use custom fields with descriptive names (MYSQL_ROOT_PASS, STRIPE_SECRET). This makes CLI/SDK retrieval straightforward and keeps records self-documenting.

Classifying secrets

To organize and locate secrets effectively, use:

• Tags — logical groupings: production, staging, development, db, cloud, k8s.
• Title — describes the secret's purpose
• Folder hierarchy — groups related secrets together

Structuring secrets

A well-designed folder structure is essential for automation. When secrets follow a predictable pattern, CLI and SDK tools can locate and collect them without manual setup.

Organization approach

Create a dedicated vault or root folder for infrastructure secrets. Inside, organize by environment and category:

infrastructure/
├── production/
│   ├── databases/
│   │   ├── mysql-primary
│   │   └── memcached-sessions
│   ├── cloud/
│   │   └── aws-credentials
│   └── k8s/
│       └── cluster-admin
├── staging/
│   ├── databases/
│   └── cloud/
└── development/
    └── local/

How this simplifies automation

Retrieve all production secrets:

passwork-cli exec --folder-id <infrastructure/production ID>

Retrieve only production DB secrets:

passwork-cli exec --folder-id <infrastructure/production/databases ID>

Naming records

Choose clear names that convey purpose:

• Good: mysql-primary, memcached-sessions, twilio-auth-token
• Avoid: secret1, temp-pass, asdf123

Descriptive naming helps you:

• find secrets quickly in the UI or via CLI search;
• understand a record's purpose at a glance;
• prevent confusion during rotation and audits.

Access control

Passwork offers granular permissions at both the vault and folder level:

• Platform team → full access to infrastructure/production and infrastructure/staging.
• Developers → access limited to infrastructure/development.
• CI/CD service (service account) → read-only access to infrastructure/production for deployments.

Permissions inherit down the folder hierarchy but can be customized at any level.

How API authentication works

Passwork API calls run as a registered account: either a person (interactive user) or a service account—a dedicated account type for scripts, CI/CD, and other automation. In both cases you use a token pair:

• Access token — authorizes API requests; limited lifetime.
• Refresh token — obtains a new access token without issuing a brand-new pair from scratch (where credential re-entry applies).

Renewing the token pair over HTTP (full rotation or access-only / refresh-only) is covered in API token rotation. Tokens are issued for the chosen account; every API call runs with that account's permissions and is recorded in the audit log under that identity. This means:

• The integration only sees vaults and folders that account can access.
• Writes are allowed only where that account has rights.
• The audit log shows which account performed the action (including service accounts).

Service accounts for integrations

For automation (CI/CD, rotation scripts, internal services), we recommend dedicated service accounts instead of personal employee accounts.

Benefits:

• Access isolation — service accounts access only the folders they need.
• Clear audit trail — logs clearly show automation-triggered actions.
• Personnel independence — staff changes don't disrupt CI/CD.
• Flexible security settings — configure separate policies for service accounts.

Recommendation

Group service accounts under a dedicated role (e.g., Service Accounts or CI/CD Integration). For this role, configure:

• API token lifetime — shorter tokens for CI/CD jobs, longer ones for always-on services.
• Password policies — relax requirements if authentication is token-only.

Sample service account layout:

Account	Purpose	Access
deploy-prod-svc	Production deployment	read-only to infrastructure/production
deploy-staging-svc	Staging deployment	read-only to infrastructure/staging
cred-rotator	Secret rotation	read-write to infrastructure/production, infrastructure/staging
health-checker	Integrity checking	read-only to all secrets

Security considerations

The "integration = user" model provides several security advantages:

1. Least privilege — each integration receives only the access it requires. Deployment CI/CD can't rotate secrets, and the rotation bot can't view dev environment data.

2. Transparent audit — every operation is logged with user, timestamp, and action type. During incidents, you can trace exactly which integration accessed a secret and when.

3. Rapid response — if an integration is compromised, revoke tokens for that specific service account without affecting others.

4. Clear responsibility — DevOps manages infrastructure service accounts while development teams handle their own.

Important

All secret operations (read, modify, delete) are recorded in Passwork's audit log, including:

• Who performed the operation (username or service account)
• When (timestamp)
• What was done (operation type, record ID)

LLM version