Core Concepts

Understanding how varsafe organizes and manages secrets.

Organizational Model

Teams

Teams are the top-level organizational unit. They represent a group of people who collaborate on projects together.

• Teams own projects
• Teams have members with roles
• Access to secrets flows through team membership
• Billing is managed at the team level
• Teams on the Team plan can configure SSO (SAML 2.0 / OIDC) for domain-based login

Projects

Projects represent applications or repositories that need secrets. Each project has:

• A name (typically matching your repository)
• An owning team
• Multiple environments
• Its own secret history

Environments

Every project has environments for different deployment stages:

Environment	Purpose	Default Protected
development	Local development	No
staging	Pre-production testing	No
production	Live systems	Yes

You can also create custom environments for specific needs (e.g., qa, demo, feature-x).

Protected environments

When an environment is marked as protected:

• Owner / Admin — read/write access
• Developer / Operator — read-only access
• Viewer / Billing — no access

Secrets

Secrets are key-value pairs stored securely:

• Key: Uppercase with underscores (e.g., DATABASE_URL)
• Value: Encrypted, up to 64KB
• Version: Auto-incremented on each change
• History: Full change history with rollback capability

---

CLI-First Architecture

varsafe is designed around the CLI workflow:

How it works

1. Authenticate — CLI presents your session token over TLS
2. Fetch — API retrieves encrypted secrets from the vault
3. Return — Decrypted secrets are sent back over TLS
4. Inject — CLI sets secrets as environment variables in the spawned process

The dashboard exists for management tasks (creating teams, inviting members, viewing audit logs) but the primary developer interaction is through the CLI.

---

Context Management

The CLI remembers your project and environment context:

# Set your working context
varsafe use -p my-api -e development

# Now these commands use that context automatically
varsafe list
varsafe run -- npm run dev
varsafe export -o .env

Save time with context

Set your context once with varsafe use and forget about -p and -e flags for the rest of your session.

Context resolution order:

1. Explicit flags (-p, -e) take priority
2. Saved context from varsafe use
3. Auto-selection if only one option exists
4. Interactive prompt if multiple options exist

Override context anytime with flags:

varsafe list -p my-api -e staging

---

Ephemeral Injection

Secrets are never written to disk by default. Instead, they're injected directly into your process's environment:

varsafe run -- npm run dev

This command:

1. Authenticates with varsafe API
2. Fetches secrets for current context
3. Spawns npm run dev with secrets as environment variables
4. Secrets exist only in the process memory

When your app terminates, the secrets are gone — no files left behind.

Ephemeral by design

Secrets injected via varsafe run exist only in process memory. If you need persistent files, use varsafe export explicitly — but remember that files on disk are harder to secure.

If you need a .env file, use varsafe export:

varsafe export -o .env

---

Access Control Model

Access follows this hierarchy:

Roles

Role	Non-Protected Envs	Protected Envs	Team Mgmt	API Tokens	Audit	Billing	Transfer/Delete
Owner	Read/Write	Read/Write	Yes	Yes	Yes	Yes	Yes
Admin	Read/Write	Read/Write	Yes	Yes	Yes	Yes	—
Developer	Read/Write	Read-only	—	—	—	—	—
Operator	Read-only	Read-only	—	—	—	—	—
Viewer	Read-only	No Access	—	—	—	—	—
Billing	No Access	No Access	—	—	—	Yes	—

By default, production is protected. You can protect or unprotect any environment via settings.

API Tokens

When to use API tokens

Use API tokens instead of user sessions for non-interactive access:

• CI/CD pipelines — Inject secrets during build and deploy
• Automation scripts — Scheduled jobs, cron tasks, infrastructure tooling
• Server-side applications — Backend services that need secrets at startup
• Development tooling — Custom scripts, internal CLIs, or IDE integrations

Token properties:

• Scoped to specific teams
• Separate audit trail (shows as service account)
• Rotatable without affecting user access
• No expiration (until revoked)

---

Version History

Every secret change is tracked in the dashboard. Operation types include:

• create — New secrets added
• update — Secret values changed
• delete — Secrets removed
• rotate — Secret rotated

Rollback

You can rollback an environment to any previous state via the dashboard:

1. Go to Secrets → History
2. Select the operation to rollback
3. Review the preview showing what will change
4. Confirm rollback

---

Audit Trail

Every action is logged:

{
  "action": "secret.accessed",
  "actor": "alice@example.com",
  "project": "api-backend",
  "environment": "production",
  "secretKeys": ["DATABASE_URL", "API_KEY"],
  "ip": "192.168.1.100",
  "source": "cli",
  "timestamp": "2026-02-15T10:30:00Z"
}

Audit logs are:

• Immutable — Cannot be modified or deleted
• Complete — Every action is logged
• Queryable — Filter by team, project, actor, or time range
• Exportable — Download for compliance (SOC2, GDPR, HIPAA)

Audit retention:

• Developer plan: 7 days
• Team plan: 90 days

---

Session Management

varsafe uses opaque session tokens for authentication:

• High-entropy tokens generated with secure randomness
• Hashed before storage — We never store your raw token
• Instantly revocable — No waiting for token expiry
• Session metadata includes IP, user agent, and timestamp

When you revoke a session, it's immediately invalid everywhere.

---

Related Documentation

• CLI Reference — Command details
• Dashboard Guide — Full dashboard features
• API Tokens — Service accounts
• Security Model — Security architecture
• Operations — Operational workflows