Operations Guide

Operational reference — secret rotation, version history and rollback, key management, audit events, retention, exports, and incident response.

Day-two operations for teams running on varsafe: rotating secrets, recovering from bad changes, managing keys and tokens, and getting audit data out. Procedures assume the role required for the action (roles reference).

Secret Rotation

Why Rotate?

• Compromised credentials
• Employee departure
• Regular security hygiene
• Compliance requirements

Rotation via Dashboard

Requires: developer role or above (owner/admin in protected environments).

1. Navigate to Secrets
2. Select the project and environment
3. Click the rotate icon next to the secret
4. Either let varsafe auto-generate a new value or enter one manually
5. Review the preview step
6. Confirm rotation

The old value is immediately replaced, and a secret.rotated audit event is recorded. Applications using varsafe run receive the new value on their next start.

Rotation via CLI

For scripted rotation, pipe the new value in. A production environment is protected, so add -y to confirm up front in a non-interactive job:

printf %s "$NEW_DATABASE_URL" | varsafe set DATABASE_URL --stdin -p my-api -e production -y

Rotation Best Practices

A reasonable default schedule:

Handling Running Applications

Applications read secrets at startup, so a rotation takes effect on the next start:

1. Stateless apps — restart to pick up new secrets
2. CI/CD — each run fetches fresh secrets automatically

Version History & Rollback

Every secret change creates a new version. Two recovery paths exist: rolling back a single secret and rolling back an entire environment to the state before a given operation.

Single-Secret Rollback

1. Navigate to Secrets, select project and environment
2. Open the secret’s History
3. Pick the version to restore and confirm

The restore is recorded as a secret.rolled_back audit event.

Environment Rollback

Use this for bulk mistakes — a bad import, an accidental bulk delete:

1. Navigate to Secrets, select project and environment
2. Click History to see the environment’s operations
3. Click Rollback next to the target operation
4. Review the preview:
   • Secrets to delete (created by the operation)
   • Secrets to restore (deleted by the operation)
   • Secrets to revert (updated by the operation)
5. Confirm

Rollback restores the environment to its state before the selected operation and records an environment.rolled_back audit event.

Encryption Key Management

Each environment has an X25519 keypair used for encrypted .env exports. Private keys are stored server-side, encrypted by KMS — varsafe manages the environment keys for you.

Auto-Rotation on Loss of Access

By default, varsafe automatically rotates the keypair of every environment whose private key someone had accessed (tracked via environment.key_accessed audit events) as soon as they lose the ability to export keys — removed from the team, leaving, or downgraded out of owner/admin. Scheduled deactivation is not covered: it takes effect after a grace period, so there is no moment at deactivation time when rotating would help. They therefore cannot decrypt exports sealed after the rotation, even if they kept a file copy.

Rotation is not retroactive: files sealed before it still open with the retained old key. If a key reached someone it should not have, rotate the underlying secrets too, not just the keypair.

To switch between automatic and manual rotation: team settings → Key rotation on loss of access (owner/admin only). The change is recorded as a team.settings_updated audit event.

After a Rotation

Existing encrypted .env files keep working: the CLI transparently re-encrypts stale files against the new keypair on the next varsafe run --env-file use. Key lifecycle actions are all audited (environment.key_generated, environment.key_rotated, environment.key_deleted).

Suggested key rotation:

API Token Management

Full reference: API Tokens. Operationally:

• Create one token per pipeline, scoped to its project and environment, with the shortest workable expiration
• Rotate on schedule: dashboard → team settings → API Tokens → Rotate; the old token is invalidated immediately
• Revoke compromised or unused tokens immediately; review last-used timestamps to find dead tokens

Audit Log Management

Event Catalog

Actions are namespaced as category.action (e.g., secret.accessed, team.member_removed).

Retention

Events past the retention window are pruned. For longer retention, export audit logs regularly and store them in your own compliance archive.

CSV Export

1. Navigate to Audit Log
2. Apply any filters needed
3. Click CSV (the download button in the toolbar)

Like the compliance exports, this writes the events currently loaded — filter to what you need before exporting.

Alert-Worthy Events

Configurable alerting is not currently exposed in the dashboard — review the audit log (or feed exports into your SIEM) and watch for these events:

Compliance Exports

Structured JSON exports of the audit trail, formatted for common review frameworks. Requires the Team plan and owner/admin role. These exports support your compliance program — they are not certifications.

There are two paths to a compliance export, and they do not produce the same file.

From the dashboard — open Audit Log, then Export and pick a format. This builds the JSON in your browser from the events currently on screen, which is one page of 25. Filter first, and treat it as a sample or a spot check rather than a period export:

From the API — POST /audit/export produces the real period export: it queries the range server-side rather than the page you are looking at, adds a member access matrix for SOC 2, and includes the IP address on every event for HIPAA. It is capped at 50,000 events per export, so narrow the range for a busy team rather than requesting a year at once.

Access Reviews

Quarterly Access Review

1. List team members:

   • Dashboard → Teams → expand each team
   • Note members and their roles

2. Review for:

   • Departed employees (should be removed)
   • Role appropriateness (least privilege — see roles)
   • Deactivated or inactive accounts

3. Take action:

   • Remove departed members (this auto-rotates environment keypairs they had key access to)
   • Downgrade excessive roles
   • Document review completion

Reviewing API Tokens

1. Go to team settings → API Tokens
2. For each token, check: is it still needed, who created it, when was it last used (timestamp, IP, and user agent are tracked)
3. Revoke unused tokens

Incident Response

Troubleshooting

Operational errors — sign-in, permissions, context resolution, rate limits — are collected in the troubleshooting guide, with the actual message text you would see and how to clear it.

One case specific to this page: Action not permitted on an operation you believe your role allows. Check, in order, that your team membership is active, that your role permits the action (roles reference), and that the environment is not protected — developers get read-only access in a protected environment, and viewers get none.