Skip to content
varsafe
Esc
↑↓navigate↵open⌘Jpreview
On this page

Core Concepts

The varsafe mental model — teams, projects, environments, secrets, context resolution, and how injection works.

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 — and a user can belong to multiple teams
  • 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), and protect or unprotect any environment in its settings.

Each environment also has a server-managed keypair used to produce encrypted .env exports — files that only your team can decrypt.

Secrets

Secrets are key-value pairs stored securely:

  • Key: starts with an uppercase letter, then uppercase letters, digits, and underscores (e.g., DATABASE_URL); up to 255 characters
  • Value: encrypted, up to 64 KB
  • Version: auto-incremented on each change
  • History: full change history with rollback capability

CLI-First Architecture

varsafe is designed around the CLI workflow:

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

Context Management

Most commands need to know which project and environment you mean. The CLI resolves context in this order:

  1. Explicit flags (-p, -e) always win
  2. Local .varsafe file — a small context file in your repository, found by searching from the current directory up to the git root
  3. Global saved context — set with varsafe use, stored in the CLI’s local database
  4. Auto-selection if only one option exists, or an interactive prompt otherwise
# 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

When you run varsafe use inside a git repository, the context is written to a .varsafe file in the repo — teammates and future shells in that repo pick it up automatically. Outside a repository, the context is saved globally.

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 the varsafe API over TLS
  2. Fetches secrets for the current context
  3. Spawns npm run dev with secrets as environment variables
  4. Secrets exist only in the child process’s environment

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

Access Control Model

Access follows this hierarchy:

Six roles exist: owner, admin, developer, operator, viewer, and billing. Owners and admins manage the team and write everywhere; developers write to non-protected environments; operators and viewers are read-only; billing members manage billing without secret access. The full permissions matrix lives in the roles reference.

API Tokens

Token properties:

  • Scoped to a specific team
  • Prefixed vs_at_ so scanners can recognize them
  • Separate audit trail (shows as a service account)
  • Optional expiration date; revocable at any time

See API tokens for creation and usage.

Version History

Every secret change is tracked. Operation types include:

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

Rollback

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

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

Audit Trail

Every action is logged. An audit event looks like this (illustrative):

{
  "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:

  • Append-only — Events are added, never edited
  • Complete — Every action is logged
  • Queryable — Filter by team, project, actor, or time range
  • Exportable — Download for compliance reviews

Audit retention is plan-gated:

  • 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 — the raw token is never stored server-side
  • 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. See the security model for the full picture.