Two-Factor Authentication

Two-factor authentication (2FA) adds a second layer of security to your account. After logging in with your API key, CLI commands that require sensitive actions verify your identity using a code from your phone or email.

Supported Methods

Method	Description
Authenticator App (TOTP)	Time-based one-time passwords from apps like Google Authenticator, Authy, or Microsoft Authenticator
SMS	A 6-digit code sent to your mobile phone
Email	Always available as a verification channel via your account email; cannot be added or removed as a method the way TOTP/SMS can. Used to authorize adding your first method (`tfa auth-new`), and also accepted as a `--method-type` for `auth-new`, `login`, `delete`, and `regen-codes` once you have 2FA set up

Setting Up 2FA

Setting up 2FA requires three steps: authorize the addition of a new method, configure the method, then activate it with a verification code.

Step 1: Authorize a new method

Before adding any 2FA method, authorize your account. For your first method, authorization uses email by default. For subsequent methods, use an existing 2FA method.

# Default (email authorization — use for first method)
vastai tfa auth-new

# Use an existing TOTP method
vastai tfa auth-new --method-type totp

# Use a backup code (skips interactive prompt)
vastai tfa auth-new --backup-code ABCD-EFGH-IJKL

When prompted, enter the code sent to your email (or existing 2FA method). If you exit before completing, resume with:

vastai tfa auth-new --secret <SECRET> --code <CODE>

Step 2: Configure the method

For Authenticator App (TOTP):

vastai tfa totp-setup

This displays a QR code and a manual entry key. Scan the QR code or type the key into your authenticator app. For SMS:

vastai tfa send-sms --phone-number +12345678901

A 6-digit code is sent to the specified phone number, and a secret token is returned. If the code expires, use vastai tfa resend-sms --secret <SECRET>.

Email is not a 2FA method you add in this step — it is the verification channel used by tfa auth-new (Step 1) to authorize adding your first method (TOTP or SMS).

Step 3: Activate the method

# TOTP (use the 6-digit code from your authenticator app and the secret from totp-setup)
vastai tfa activate --method-type totp --secret <SECRET> <CODE>

# SMS (use the code received via SMS and the secret from send-sms)
vastai tfa activate --method-type sms --secret <SECRET> --phone-number +12345678901 <CODE>

# Optional: add a label
vastai tfa activate --method-type totp --secret <SECRET> --label "Work Authenticator" <CODE>

After activating your first 2FA method, backup codes are generated and you’re prompted to choose how to save them: to a default file under ~/Downloads, to a custom path, or printed to the screen (the CLI warns this option is visible to onlookers). Save these backup codes in a secure location — they are the only way to recover access if you lose your 2FA device. The default file-save options write an unencrypted text file, so treat the resulting file the same as the codes themselves.

Logging In with 2FA

If your account has 2FA enabled and your session key has expired, use tfa login to re-authenticate:

# TOTP (Authenticator app)
vastai tfa login --method-type totp --code 123456

# SMS (get a new code with send-sms first)
vastai tfa login --method-type sms --code 123456 --secret <SECRET>

# Email
vastai tfa login --method-type email --code 123456 --secret <SECRET>

# Backup code (one-time use)
vastai tfa login --backup-code ABCD-EFGH-IJKL

On success, the session key is saved to ~/.config/vastai/vast_tfa_key. The CLI uses this session key for subsequent authenticated requests. If the session expires, the CLI doesn’t just fail — it deletes the stale session key and automatically retries using your plain API key instead, printing a message like “Your 2FA session has expired… Trying again with your normal API Key”. Run tfa login again only when you actually need a fresh 2FA session for a later command.

Managing Methods

View current status

vastai tfa status

Shows whether 2FA is enabled, lists all active methods with their IDs, and shows the number of remaining backup codes.

Update a method

# Rename a method
vastai tfa update 123 --label "Personal Phone"

# Set as primary/default
vastai tfa update 123 --set-primary t

Use the method ID from vastai tfa status.

Delete a method

# Delete method #123, verify with TOTP
vastai tfa delete --id-to-delete 123 --method-type totp --code 456789

# Verify with backup code
vastai tfa delete --id-to-delete 123 --backup-code ABCD-EFGH-IJKL

# Verify with SMS (requires secret from send-sms)
vastai tfa delete --id-to-delete 123 --method-type sms --secret <SECRET> --code 456789

The CLI asks you to confirm (y/n) before deleting, since this invalidates the method’s own codes.

Deleting your last 2FA method fully disables 2FA and invalidates all backup codes.

Backup Codes

Backup codes let you log in if you lose access to your 2FA device. Each code is one-time use.

Regenerate backup codes

# Verify with TOTP
vastai tfa regen-codes --code 123456 --method-type totp

# Verify with backup code
vastai tfa regen-codes --backup-code ABCD-EFGH-IJKL

The CLI asks you to confirm (y/n) before regenerating, since this invalidates every existing code. On success, same interactive save prompt as the initial activation (default file under ~/Downloads, a custom path, or print to screen).

Regenerating codes invalidates all existing backup codes immediately. Save the new codes in a secure location — they are not shown again.

Session Key Lifecycle

After a successful tfa login, a session key is saved to ~/.config/vastai/vast_tfa_key (or $XDG_CONFIG_HOME/vastai/vast_tfa_key if XDG_CONFIG_HOME is set). The CLI automatically uses this key for authenticated requests. The session key expires after inactivity. When a command hits an expired session, the CLI deletes the stale key and automatically retries using your plain API key instead — you don’t need to do anything for that fallback to happen. Run vastai tfa login again only when you actually need a 2FA session for a subsequent command.

Error Reference

Error Code	Meaning	Action
`2fa_verification_failed`	Incorrect code entered	Check the code and retry; check `fail_count` in output
`tfa_locked`	Too many failed attempts	Wait for the lock to expire (`locked_until` shown in output)
`2fa_expired`	SMS or email code has expired	For SMS, run `vastai tfa send-sms` again; for email, run `vastai tfa send-email` again
`authorization_required`	Tried to add a new 2FA method without prior authorization	Run `vastai tfa auth-new` first, then retry

CLI

SDK

Supported Methods

Setting Up 2FA

Step 1: Authorize a new method

Step 2: Configure the method

Step 3: Activate the method

Logging In with 2FA

Managing Methods

View current status

Update a method

Delete a method

Backup Codes

Regenerate backup codes

Session Key Lifecycle

Error Reference

See Also

​Supported Methods

​Setting Up 2FA

​Step 1: Authorize a new method

​Step 2: Configure the method

​Step 3: Activate the method

​Logging In with 2FA

​Managing Methods

​View current status

​Update a method

​Delete a method

​Backup Codes

​Regenerate backup codes

​Session Key Lifecycle

​Error Reference

​See Also

Supported Methods

Setting Up 2FA

Step 1: Authorize a new method

Step 2: Configure the method

Step 3: Activate the method

Logging In with 2FA

Managing Methods

View current status

Update a method

Delete a method

Backup Codes

Regenerate backup codes

Session Key Lifecycle

Error Reference

See Also