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).

Navigate to Secrets
Select the project and environment
Click the rotate icon next to the secret
Either let varsafe auto-generate a new value or enter one manually
Review the preview step
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, set the new value directly:

varsafe set DATABASE_URL "postgres://new-value" -p my-api -e production

Rotation Best Practices

Recommended rotation schedule

Secret Type	Rotation Frequency
API keys	Every 90 days
Database passwords	Every 90 days
Encryption keys	Annually
After incident	Immediately
:::

Handling Running Applications

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

Stateless apps — restart to pick up new secrets
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

Navigate to Secrets, select project and environment
Open the secret’s History
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:

Navigate to Secrets, select project and environment
Click History to see the environment’s operations
Click Rollback next to the target operation
Review the preview:
- Secrets to delete (created by the operation)
- Secrets to restore (deleted by the operation)
- Secrets to revert (updated by the operation)
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 Member Removal

By default, varsafe automatically rotates the keypair of every environment whose private key a removed member had accessed (tracked via environment.key_accessed audit events). Removed members therefore cannot decrypt future exports even if they kept a file copy.

To switch between automatic and manual rotation: team settings → Key rotation on member removal (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).

Rotation schedule

Key Type	Rotation Frequency
Environment keypairs	Auto on member removal, or annually
After suspected exposure	Immediately
:::

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

Category	Actions
Auth	`login`, `logout`, `login_failed`, `session_revoked`, `2fa_enabled`, `2fa_disabled`, `passkey_added`, `passkey_removed`, `passkey_only_enabled`, `passkey_only_disabled`, `device_trusted`, `device_untrusted`, `login_otp_verified`, `risky_login_detected`
Secrets	`created`, `updated`, `deleted`, `accessed`, `rotated`, `exported`, `rolled_back`
Environments	`created`, `updated`, `deleted`, `rolled_back`, `key_generated`, `key_accessed`, `key_access_denied`, `key_rotated`, `key_deleted`
Projects	`created`, `updated`, `deleted`
Teams	`created`, `updated`, `deleted`, `settings_updated`, `member_invited`, `member_added`, `member_removed`, `member_left`, `member_role_changed`, `member_deactivated`, `member_reactivated`, `ownership_transferred`, `invite_revoked`
API tokens	`created`, `updated`, `rotated`, `revoked`, `deleted`
SSO	`configured`, `updated`, `deleted`
Billing	`email_updated`, subscription lifecycle events
MCP	grant lifecycle, session lifecycle, and tool usage events

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

Retention

Plan	Retention
Developer	7 days
Team	90 days

Events past the retention window are pruned.

CSV Export

Navigate to Audit Log
Apply any filters needed
Click Export CSV

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:

Monitor your audit logs for these events

Event	Concern
Multiple `auth.login_failed`	Brute force attempt
`secret.accessed` (production)	Verify authorized access
`team.member_invited` (admin role)	Privilege escalation
`auth.2fa_disabled`	Security downgrade
`environment.key_access_denied`	Unauthorized key access attempt
Unfamiliar IP addresses	Unauthorized access
:::

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.

SOC 2

Navigate to Audit Log
Set the date range (audit period)
Click Export → SOC 2
Download the JSON file

Includes security-relevant events, authentication events, secret access logs, and a member access matrix.

HIPAA

Navigate to Audit Log
Click Export → HIPAA
Download the JSON file

Formats access events and authentication events for access-control review.

Access Reviews

Quarterly Access Review

List team members:
- Dashboard → Teams → expand each team
- Note members and their roles
Review for:
- Departed employees (should be removed)
- Role appropriateness (least privilege — see roles)
- Deactivated or inactive accounts
Take action:
- Remove departed members (this auto-rotates environment keypairs they had key access to)
- Downgrade excessive roles
- Document review completion

Reviewing API Tokens

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

varsafe login

Permission denied

Check:

Team membership exists (and is not deactivated)
The role permits the action (roles reference)
The environment is not protected (developers get read-only access there; viewers none)

Project not found

Either:

Create the project in the dashboard
Use varsafe use to set context
Specify with the -p flag

Rate limited

Wait and retry. If persistent:

Check for automation running too frequently
Contact support for a limit increase