Authentication

Every way to sign in to varsafe — dashboard login methods, account protection, sessions, and the three CLI authentication modes.

varsafe has two authentication surfaces: the dashboard (browser sessions, including email/password) and the CLI (browser-assisted login or API tokens — no password ever reaches the terminal). This page is the reference for both, plus the account-protection features layered on top: passkeys, two-factor authentication, device trust, and session management.

Dashboard Login Methods

OAuth Login

Click the provider button on the login page. You are redirected to the provider to authorize varsafe, then returned with a session created automatically. If an account with your email already exists and the provider confirms the email is verified, the OAuth identity is linked to it.

Passkeys

Passkeys provide passwordless, phishing-resistant authentication using biometrics (Touch ID, Face ID) or hardware security keys (YubiKey). Passkey credentials are bound to the varsafe domain via WebAuthn.

Adding a Passkey

1. Navigate to Profile → Security
2. Click Add passkey
3. Enter a name (e.g., “MacBook Pro Touch ID”, “YubiKey 5”)
4. Follow your browser’s WebAuthn prompt
5. Confirm with biometrics or a security key tap

You can register multiple passkeys for redundancy.

Passkey-Only Mode

Passkey-only mode disables password login entirely, requiring a passkey for every sign-in. This is the strongest protection against phishing and credential theft.

To enable:

1. Register at least 2 passkeys (for recovery) — enabling fails with fewer
2. Go to Profile → Security
3. Toggle Passkey-only mode on

To disable:

1. Go to Profile → Security
2. Toggle Passkey-only mode off
3. Enter your password to confirm

Removing a Passkey

1. Go to Profile → Security
2. Find the passkey in the list
3. Click Remove

Two-Factor Authentication (2FA)

Add a second layer of protection with TOTP (Time-based One-Time Password).

Enable 2FA

1. Go to Profile → Security
2. Click Enable 2FA
3. Enter your password
4. Scan the QR code with an authenticator app (Google Authenticator, Authy, 1Password, etc.)
5. Enter the 6-digit verification code
6. Save your backup codes — store them somewhere safe

Using 2FA

After entering your email and password, you are prompted for a 6-digit code from your authenticator app. Codes rotate every 30 seconds.

Backup Codes

Backup codes are single-use codes for when you lose access to your authenticator app. Each code can only be used once. Store them in a password manager or another secure location.

Disable 2FA

1. Go to Profile → Security
2. Click Disable 2FA
3. Enter your password and a valid TOTP code to confirm

Device Trust

When you sign in with email/password from a device varsafe does not recognize, it sends a one-time verification code to your email. Once verified, the device is marked as trusted and skips email verification on future logins.

How It Works

1. You sign in with email/password from an unrecognized device
2. varsafe sends a one-time code to your email
3. Enter the code to complete sign-in
4. The device is trusted for future logins

Device trust is skipped for:

• Passkey login — passkeys are already device-bound
• OAuth login — the provider handles device verification
• First login after registration — the device used to register is trusted automatically

Managing Trusted Devices

There is no trusted-device screen in the dashboard yet — the Profile → Security page lists active sessions, which is a different thing: signing a session out does not untrust the device it came from. Trusted devices are managed through the API:

These act on your own devices and need your session, so they are called from a signed-in browser rather than with an API token.

Untrusting a device means the next login from it requires email verification again.

Session Management

Viewing Sessions

1. Go to Profile → Security → Active Sessions
2. See all active sessions with:
   • Device and browser info
   • IP address
   • Last active time
   • Whether it is the current session

Revoking Sessions

• Click Revoke next to any session to end it immediately
• Click Revoke all other sessions to keep only your current session

Revocation is immediate — the revoked session cannot make further requests.

Session Limits

Each plan has a maximum number of concurrent sessions per user:

When you hit the session limit, you are prompted to revoke an existing session before signing in.

Session Properties

• Duration — a session expires 7 days after its last renewal
• Rolling renewal — any authenticated request more than 1 hour after the last renewal silently extends the session by another 7 days, so active users stay signed in and idle sessions expire within a week
• Revocation — changing or resetting your password revokes all sessions

CLI Authentication

The CLI supports two authentication modes: a browser-assisted login for humans, and API tokens for machines. varsafe login uses the browser flow by default.

Browser Login (default)

varsafe login

What happens:

1. The CLI requests a human-readable confirmation code (e.g., brave-otter-374-jade-alice) and prints it along with a dashboard URL
2. Your browser opens to the dashboard, where you sign in (if needed) and confirm that the code on screen matches the one in your terminal
3. The CLI waits on a server-sent event stream for the confirmation; if the stream is unavailable it falls back to polling
4. On confirmation, the CLI receives a session and stores it in the local credential store

The confirmation code expires after 5 minutes. Run varsafe login --force to re-authenticate when a session already exists.

API Token

For CI/CD and automation, use an API token. There are several ways to pass a token, and passing it as a plain CLI argument is not one of them — the CLI refuses that outright.

Secure prompt (recommended for interactive use)

varsafe login -T
# or
varsafe login --token-prompt

Prompts for the token with masked input — nothing is saved to shell history.

Stdin pipe

echo "$VARSAFE_TOKEN" | varsafe login -t -
# or from a file
varsafe login -t - < /dev/shm/token.txt

The - argument tells the CLI to read the token from stdin.

Environment variable (recommended for CI/CD)

This is the method to reach for in a pipeline, and it involves no login step at all. The CLI accepts VARSAFE_API_TOKEN, with VARSAFE_TOKEN as a fallback alias:

export VARSAFE_API_TOKEN=vs_at_vsafe_example
varsafe run -- npm run dev

When the variable is set, the CLI authenticates with it instead of a stored user session. Inject it from your CI secrets store — see the CI/CD guide.

Why there is no --token <value> flag

# Rejected, by design
varsafe login --token "$VARSAFE_TOKEN"

An inline value would be visible in shell history and to any process that can read ps output, so the CLI refuses it and points you at the alternatives above. --token with no value means “prompt me”; --token - means “read stdin”.

Credential Storage

CLI credentials are kept in an encrypted local store (SQLite with AES-256-GCM encryption) under ~/.varsafe. Credentials are never written in plaintext.

Password Reset

1. Click Forgot password? on the login page
2. Enter your email address
3. Check your email for a reset link (valid for 1 hour)
4. Click the link and set a new password