Authentication

Every way to sign in to varsafe — dashboard login methods, account protection, sessions, and the CLI's browser and token sign-in.

People sign in to the dashboard in the browser, and the CLI signs in through that same browser, so a password never reaches a terminal. Machines use API tokens.

Dashboard login methods

SSO is detected from your email. Type your work email on the sign-in page: if your company has set up SSO for that domain, the page offers Continue with SSO. Use password instead remains available.

OAuth login

Click a provider button, approve varsafe at the provider, and you are signed in.

If an account with the same email already exists under another method, the provider sign-in is refused rather than silently attached to that account, which stops anyone from taking over an account through a provider that vouches for an email they do not own. The sign-in page says There is already a varsafe account with this email: sign in the way you did before, then connect the provider from your profile.

Connected accounts

Connected accounts on your Profile lists GitHub, GitLab, Google and Bitbucket, and which of them are connected.

• Connect sends you to the provider to approve, then back to your profile. The provider account must use the same email address as your varsafe account, and the provider must have confirmed it. Your own email must be confirmed first.
• Disconnect stops that provider signing you in. It is refused when your account has no password and no other provider, and it needs a session signed in within the last day.

A provider account already connected to another varsafe account cannot be connected to yours.

Connecting or disconnecting a provider here is recorded in your audit log as auth.provider_connected or auth.provider_disconnected, naming the provider, and is not kept if the record cannot be written.

Confirming your email

A new account can be used straight away. varsafe sends a confirmation link, valid for 24 hours. You need to have confirmed your email before you:

• invite someone or accept an invite
• create a team
• transfer ownership
• configure SSO
• connect an AI agent
• connect a sign-in provider

Passkeys

Passkeys sign you in with Touch ID, Face ID, Windows Hello or a hardware key such as a YubiKey, with no password to phish or reuse. Each passkey is bound to the varsafe domain.

Adding a passkey

1. Open your Profile in the dashboard
2. In the Passkeys card, click Add passkey
3. Optionally name it (“MacBook Touch ID”, “YubiKey 5”)
4. Follow your browser’s prompt

Register more than one, on different devices, so losing one device does not lock you out. Passkeys can be renamed or deleted from the same card.

Passkey-only mode

Passkey-only mode refuses every sign-in that is not a passkey: password, GitHub, GitLab, Google, Bitbucket and SSO. A refused sign-in says This account is in passkey-only mode. Sign in with one of its passkeys.

• Requirements: at least 2 passkeys and a password on the account. The Passkey-only mode control appears in the Passkeys card once both are in place.
• Enabling it revokes every session, including the current one. Sign back in with a passkey.
• While it is on, a session signed in with a passkey can still change the password and turn two-factor authentication on or off.
• Disabling it takes your password.

Two-factor authentication (2FA)

Two-factor authentication adds a time-based one-time code (TOTP) to password sign-in. It is available on accounts that have a password.

Enable 2FA

Using 2FA

Session management

Viewing sessions

The Active Sessions card on your Profile lists every browser signed in to your account, with its device and browser, IP address and last activity. Current marks the one you are using.

Revoking sessions

• The revoke button on a row (Revoke session) signs that browser out
• Revoke all other sessions keeps only the current one

A revoked session stops working within 30 seconds.

Session properties

• Lifetime: a session ends 7 days after it was last extended. Using it extends it, at most once an hour, so an active session stays signed in and an idle one ends within a week.
• Renewal: changing the password with Sign out all other devices, or turning two-factor authentication on or off, replaces the session you are using with a new one. The audit log records it as auth.session_renewed, with the reason and the session it replaced, not as a sign-in.
• Concurrent sessions: the plan sets a threshold of 5 per person on Developer (200 on Team). It is a prompt, not a ceiling: past it the dashboard shows Session limit reached after sign-in and offers to revoke old sessions, but you can continue and a new session is still created.

CLI logins are listed separately, in the CLI Sessions card on your Profile.

Password change and reset

Changing your password, from your Profile, keeps your other sessions signed in unless you tick Sign out all other devices. Tick it if you are changing the password because you think someone else knows it. Each change is recorded in your audit log as auth.password_changed, saying whether the other devices were signed out; a reset is recorded as auth.password_reset.

Resetting a forgotten password:

1. Click Forgot password? on the sign-in page
2. Enter your email address
3. Open the link in the email within 1 hour and choose a new password

CLI authentication

The CLI has two ways in: a browser login for people, and an API token for machines. There is no email and password login in the terminal.

Browser login (default)

varsafe login

1. The CLI shows a confirmation code such as 7KQ2M-X9D4F and opens the dashboard approval page (it prints the URL if no browser opens)
2. In the browser, sign in if needed, check that the code matches the one in your terminal, and approve
3. The CLI picks up the approval at once, over a live connection that falls back to polling every few seconds

The code expires after 10 minutes. varsafe login --force signs in again when a login already exists.

A CLI login is its own credential, not a copy of your browser session. It lasts at most 180 days from approval and ends sooner if the machine goes 90 days without using it. Revoke one any time from the CLI Sessions card on your Profile. Removing you from a team revokes your CLI login for that team.

API token

For CI/CD and automation, use an API token. Pick the input that keeps the value out of shell history:

Environment variable (recommended for CI/CD)

No login step at all. Set VARSAFE_API_TOKEN (or VARSAFE_TOKEN, read when the first is not set) from your CI secret store:

export VARSAFE_API_TOKEN=vs_at_vsafe_example
varsafe run -- npm run build

The variable is used when the machine has no stored login. If varsafe login has stored a credential, that credential takes precedence and the variable is ignored; varsafe whoami shows which one a command will use. See the CI/CD guide.

Secure prompt (recommended at a workstation)

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

Masked input; nothing lands in shell history.

Stdin pipe

secret-manager read varsafe-token | varsafe login -t -
# or from a file in RAM
varsafe login -t - < /dev/shm/token.txt

- tells the CLI to read the token from standard input.

From VARSAFE_TOKEN

VARSAFE_TOKEN=vs_at_vsafe_example varsafe login

A bare varsafe login with VARSAFE_TOKEN set stores that token as the login.

Why there is no --token <value> flag

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

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

Credential storage

The CLI keeps its credential in ~/.varsafe/varsafe.db. Which credential it is decides how it is stored, how long it lasts and what signing out does:

The encryption key is kept in the operating system keychain (macOS Keychain, or the Secret Service on Linux), so a copy of the file alone does not reveal the credential. varsafe doctor checks that the keychain works on this machine.

The machine token is what a browser login falls back to on a machine with no keychain: there is no keychain to hold a key, so it is stored unencrypted. To limit what a copied file is worth, it is restricted to one team and the projects and environments you approved.

Signing out

varsafe logout

For an API token stored with varsafe login -T, logout clears the token from the machine only: revoke the token itself in the dashboard if the machine is no longer trusted.

Deleting your account

Open your Profile, go to Danger Zone, and type delete my account to confirm. Deletion is permanent.

What sign-in does not do yet

• No new-device check. A correct password from an unfamiliar device is not challenged by email. Turn on two-factor authentication or use passkeys.
• SSO is not enforced. Setting up SSO for a domain does not stop its users from signing in with a password or a provider.
• No provider account under another email. A provider can be connected only with the same email address as your varsafe account.