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) and the CLI (browser-assisted login, email/password, or API tokens). 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

1. Go to Profile → Security → Trusted Devices
2. See all trusted devices with browser and OS info
3. Click Remove next to a device to untrust it
4. Click Remove all to untrust every device

Removing a trusted device means the next login from that device 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 three authentication modes. varsafe login picks the browser flow by default in an interactive terminal, and falls back to email/password otherwise.

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.

Email/Password

varsafe login --no-browser
# or provide the email up front
varsafe login -e you@example.com

Prompts for your password in the terminal. To register a new account from the CLI:

varsafe login --register

API Token

For CI/CD and automation, use an API token. There are several ways to pass a token securely — never pass it as a plain CLI argument, since it leaks into shell history.

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.

Environment variable (recommended for CI/CD)

VARSAFE_TOKEN=vs_at_vsafe_example varsafe login

varsafe login reads VARSAFE_TOKEN from the environment when no explicit token is provided. In CI pipelines, inject the token from your CI secrets store — see the CI/CD guide.

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.

Direct argument (not recommended)

varsafe login -t vs_at_vsafe_example

Headless use without login

For one-off commands, skip varsafe login entirely and set the environment variable. 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 your stored user session.

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