diff --git a/cli/reference/tfa-activate.mdx b/cli/reference/tfa-activate.mdx
new file mode 100644
index 00000000..92fd83bb
--- /dev/null
+++ b/cli/reference/tfa-activate.mdx
@@ -0,0 +1,63 @@
+---
+title: "vastai tfa activate"
+sidebarTitle: "tfa activate"
+---
+
+Activate a new 2FA method by verifying the code. Run `vastai tfa auth-new` before this command to authorize adding a new method.
+
+## Usage
+
+```bash
+vastai tfa activate CODE --secret SECRET [--method-type METHOD_TYPE] [--phone-number PHONE_NUMBER] [--label LABEL]
+```
+
+## Arguments
+
+
+ 6-digit verification code from SMS or Authenticator app.
+
+
+## Options
+
+
+ Secret token from the setup process. For TOTP, obtained from `vastai tfa totp-setup`. For SMS, obtained from `vastai tfa send-sms`.
+
+
+
+ New 2FA method type to activate. Choices: `sms`, `totp`. Treated as `totp` when neither this flag nor `--phone-number` is supplied.
+
+
+
+ Phone number for SMS method in E.164 format (e.g., `+12345678901`). Required when activating an SMS method.
+
+
+
+ Friendly label for the new 2FA method (e.g., "Work Authenticator").
+
+
+## Examples
+
+```bash
+# Activate TOTP (Authenticator app)
+vastai tfa activate --method-type totp --secret abc123def456 123456
+
+# Activate SMS
+vastai tfa activate --method-type sms --secret abc123def456 --phone-number +12345678901 123456
+
+# Activate SMS with a label
+vastai tfa activate --method-type sms --secret abc123def456 --phone-number +12345678901 --label "Work Phone" 123456
+```
+
+If this is your **first** 2FA method, backup codes are generated and displayed after activation. Save them in a secure location.
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-auth-new.mdx b/cli/reference/tfa-auth-new.mdx
new file mode 100644
index 00000000..aab31862
--- /dev/null
+++ b/cli/reference/tfa-auth-new.mdx
@@ -0,0 +1,68 @@
+---
+title: "vastai tfa auth-new"
+sidebarTitle: "tfa auth-new"
+---
+
+Authorize your account to add a new 2FA method. This step is required before running `vastai tfa activate`. For your first method, verification defaults to email. For subsequent methods, use an existing 2FA method.
+
+## Usage
+
+```bash
+vastai tfa auth-new {[--method-type METHOD_TYPE | --method-id ID | --backup-code BACKUP_CODE] | [--secret SECRET --code CODE]}
+```
+
+## Options
+
+
+ 2FA method type to use for authorization. Choices: `email`, `sms`, `totp`. Defaults to `email`. Only use when you have exactly one method of this type.
+
+
+
+ 2FA method ID to use if you have more than one of the same type. Get the ID from `vastai tfa status`.
+
+
+
+ One-time backup code. Using a backup code immediately authorizes without an interactive code prompt.
+
+
+
+ Secret token from a previous incomplete authorization attempt. Use with `--code` to resume.
+
+
+
+ 2FA code from a previous incomplete authorization attempt. Use with `--secret` to resume.
+
+
+## Examples
+
+```bash
+# Default: authorize via email (use for first 2FA method)
+vastai tfa auth-new
+
+# Authorize via TOTP (existing Authenticator app)
+vastai tfa auth-new --method-type totp
+
+# Authorize via SMS
+vastai tfa auth-new -t sms
+
+# Authorize using a specific method ID
+vastai tfa auth-new --method-id 456
+
+# Authorize with backup code (no interactive prompt)
+vastai tfa auth-new --backup-code ABCD-EFGH-IJKL
+
+# Resume a previous incomplete authorization
+vastai tfa auth-new --secret abc123def456 --code 123456
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-delete.mdx b/cli/reference/tfa-delete.mdx
new file mode 100644
index 00000000..3154ebce
--- /dev/null
+++ b/cli/reference/tfa-delete.mdx
@@ -0,0 +1,71 @@
+---
+title: "vastai tfa delete"
+sidebarTitle: "tfa delete"
+---
+
+Remove a 2FA method from your account. Requires 2FA verification to authorize the deletion.
+
+## Usage
+
+```bash
+vastai tfa delete [--id-to-delete ID] [--code CODE] [--method-type METHOD_TYPE] [--secret SECRET] [--backup-code BACKUP_CODE] [--method-id ID]
+```
+
+## Options
+
+
+ ID of the 2FA method to delete. Get the ID from `vastai tfa status`. If omitted, the system attempts to delete the method you are using to authenticate — specify this flag explicitly when you have multiple methods to avoid ambiguity.
+
+
+
+ 2FA code from your Authenticator app, SMS, or Email to authorize the deletion. Exactly one of `--code` or `--backup-code` is required.
+
+
+
+ One-time backup code to authorize the deletion. Exactly one of `--code` or `--backup-code` is required.
+
+
+
+ 2FA method type to use for authorization. Choices: `email`, `sms`, `totp`. Only use when you have exactly one method of this type.
+
+
+
+ Secret token required when authorizing with `--method-type sms` or `--method-type email`. Obtain from `vastai tfa send-sms` or `vastai tfa send-email`.
+
+
+
+ ID of the 2FA method to use for authorization if you have more than one of the same type. Get the ID from `vastai tfa status`.
+
+
+## Examples
+
+```bash
+# Delete method #123, authorize with TOTP
+vastai tfa delete --id-to-delete 123 --method-type totp --code 456789
+
+# Delete method #123, authorize with backup code
+vastai tfa delete --id-to-delete 123 --backup-code ABCD-EFGH-IJKL
+
+# Delete method #123, authorize with SMS (get secret from send-sms first)
+vastai tfa delete --id-to-delete 123 --method-type sms --secret abc123def456 --code 456789
+
+# Delete method #123, authorize with Email (get secret from send-email first)
+vastai tfa delete --id-to-delete 123 --method-type email --secret abc123def456 --code 456789
+
+# Specify which TOTP method to use for authorization if you have multiple
+vastai tfa delete --id-to-delete 123 --method-id 456 --code 456789
+```
+
+**Warning:** Deleting your last 2FA method fully disables 2FA and invalidates all backup codes.
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-login.mdx b/cli/reference/tfa-login.mdx
new file mode 100644
index 00000000..136c3788
--- /dev/null
+++ b/cli/reference/tfa-login.mdx
@@ -0,0 +1,62 @@
+---
+title: "vastai tfa login"
+sidebarTitle: "tfa login"
+---
+
+Complete 2FA login by verifying your identity with a 2FA code or backup code. On success, saves the session key to `~/.config/vastai/vast_tfa_key`.
+
+## Usage
+
+```bash
+vastai tfa login [--code CODE] [--method-type METHOD_TYPE] [--secret SECRET] [--backup-code BACKUP_CODE] [--method-id ID]
+```
+
+## Options
+
+
+ 2FA code from Authenticator app, SMS, or Email. Exactly one of `--code` or `--backup-code` is required.
+
+
+
+ One-time backup code (alternative to regular 2FA code). Exactly one of `--code` or `--backup-code` is required.
+
+
+
+ 2FA method type. Choices: `email`, `sms`, `totp`. Only use when you have exactly one method of this type.
+
+
+
+ Secret token from the previous login step. Required for SMS or Email 2FA (obtained from `tfa send-sms` or `tfa send-email`).
+
+
+
+ 2FA method ID if you have more than one of the same type. Get the ID from `vastai tfa status`.
+
+
+## Examples
+
+```bash
+# Login with TOTP (Authenticator app)
+vastai tfa login --method-type totp -c 123456
+
+# Login with SMS (get code and secret from send-sms first)
+vastai tfa login --method-type sms --code 123456 --secret abc123def456
+
+# Login with Email
+vastai tfa login -t email -c 123456 -s abc123def456
+
+# Login with backup code
+vastai tfa login --backup-code ABCD-EFGH-IJKL
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-regen-codes.mdx b/cli/reference/tfa-regen-codes.mdx
new file mode 100644
index 00000000..744dc3dc
--- /dev/null
+++ b/cli/reference/tfa-regen-codes.mdx
@@ -0,0 +1,61 @@
+---
+title: "vastai tfa regen-codes"
+sidebarTitle: "tfa regen-codes"
+---
+
+Generate a new set of backup codes. Requires 2FA verification.
+
+## Usage
+
+```bash
+vastai tfa regen-codes [--code CODE] [--method-type METHOD_TYPE] [--secret SECRET] [--backup-code BACKUP_CODE] [--method-id ID]
+```
+
+## Options
+
+
+ 2FA code from your Authenticator app, SMS, or Email. Exactly one of `--code` or `--backup-code` is required.
+
+
+
+ One-time backup code to authorize regeneration. Exactly one of `--code` or `--backup-code` is required.
+
+
+
+ 2FA method type to use for verification. Choices: `email`, `sms`, `totp`. Only use when you have exactly one method of this type.
+
+
+
+ Secret token required when verifying with `--method-type sms` or `--method-type email`. Obtain from `vastai tfa send-sms` or `vastai tfa send-email`.
+
+
+
+ ID of the 2FA method to use for verification if you have more than one of the same type. Get the ID from `vastai tfa status`.
+
+
+## Examples
+
+```bash
+# Verify with TOTP (Authenticator app)
+vastai tfa regen-codes --code 123456 --method-type totp
+
+# Verify with SMS (get secret from send-sms first)
+vastai tfa regen-codes --code 123456 --method-type sms --secret abc123def456
+
+# Verify with a backup code
+vastai tfa regen-codes --backup-code ABCD-EFGH-IJKL
+```
+
+**Warning:** Regenerating codes immediately invalidates all existing backup codes. Save the new codes in a secure location — they are not shown again.
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-resend-sms.mdx b/cli/reference/tfa-resend-sms.mdx
new file mode 100644
index 00000000..652da1d7
--- /dev/null
+++ b/cli/reference/tfa-resend-sms.mdx
@@ -0,0 +1,44 @@
+---
+title: "vastai tfa resend-sms"
+sidebarTitle: "tfa resend-sms"
+---
+
+Resend an SMS 2FA verification code. Use this if you didn't receive the original code or it expired.
+
+## Usage
+
+```bash
+vastai tfa resend-sms --secret SECRET [--phone-number PHONE_NUMBER]
+```
+
+## Options
+
+
+ Secret token from the original `vastai tfa send-sms` request.
+
+
+
+ Phone number to resend the code to in E.164 format (e.g., `+12345678901`). If omitted, uses the phone number from the original request.
+
+
+## Examples
+
+```bash
+# Resend to the same phone number as the original request
+vastai tfa resend-sms --secret abc123def456
+
+# Resend to a specific phone number
+vastai tfa resend-sms --secret abc123def456 --phone-number +12345678901
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-send-email.mdx b/cli/reference/tfa-send-email.mdx
new file mode 100644
index 00000000..69232da6
--- /dev/null
+++ b/cli/reference/tfa-send-email.mdx
@@ -0,0 +1,36 @@
+---
+title: "vastai tfa send-email"
+sidebarTitle: "tfa send-email"
+---
+
+Request a 2FA verification code via email. Returns a secret token needed for the next step (`vastai tfa login`).
+
+## Usage
+
+```bash
+vastai tfa send-email
+```
+
+## Examples
+
+```bash
+vastai tfa send-email
+```
+
+The command sends a code to your registered email address and prints a secret token. Use both to complete your 2FA login:
+
+```bash
+vastai tfa login --method-type email --secret --code
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-send-sms.mdx b/cli/reference/tfa-send-sms.mdx
new file mode 100644
index 00000000..bf7d0eb1
--- /dev/null
+++ b/cli/reference/tfa-send-sms.mdx
@@ -0,0 +1,52 @@
+---
+title: "vastai tfa send-sms"
+sidebarTitle: "tfa send-sms"
+---
+
+Request a 2FA verification code via SMS. Returns a secret token needed for the next step (`vastai tfa activate` or `vastai tfa login`).
+
+## Usage
+
+```bash
+vastai tfa send-sms [--phone-number PHONE_NUMBER]
+```
+
+## Options
+
+
+ Phone number to receive the SMS code in E.164 format (e.g., `+12345678901`). If omitted, uses the phone number on your account.
+
+
+## Examples
+
+```bash
+# Send to the phone number on your account
+vastai tfa send-sms
+
+# Send to a specific phone number
+vastai tfa send-sms --phone-number +12345678901
+```
+
+The command prints a secret token. Use it with the code you receive:
+
+```bash
+# If setting up SMS 2FA for the first time
+vastai tfa activate --method-type sms --secret --phone-number +12345678901
+
+# If completing a 2FA login
+vastai tfa login --method-type sms --secret --code
+```
+
+If the code expires before you use it, run `vastai tfa resend-sms --secret ` to get a new one.
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-status.mdx b/cli/reference/tfa-status.mdx
new file mode 100644
index 00000000..edd0addc
--- /dev/null
+++ b/cli/reference/tfa-status.mdx
@@ -0,0 +1,30 @@
+---
+title: "vastai tfa status"
+sidebarTitle: "tfa status"
+---
+
+Show the current 2FA status for your account, including whether 2FA is enabled, all active methods, and the number of backup codes remaining.
+
+## Usage
+
+```bash
+vastai tfa status
+```
+
+## Examples
+
+```bash
+vastai tfa status
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-totp-setup.mdx b/cli/reference/tfa-totp-setup.mdx
new file mode 100644
index 00000000..861f665c
--- /dev/null
+++ b/cli/reference/tfa-totp-setup.mdx
@@ -0,0 +1,40 @@
+---
+title: "vastai tfa totp-setup"
+sidebarTitle: "tfa totp-setup"
+---
+
+Generate a TOTP secret and QR code for setting up an Authenticator app. Run `vastai tfa auth-new` before this command to authorize adding a new method.
+
+## Usage
+
+```bash
+vastai tfa totp-setup
+```
+
+## Examples
+
+```bash
+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 (Google Authenticator, Authy, Microsoft Authenticator, 1Password, or any TOTP-compatible app).
+
+After adding the account to your app, complete setup with:
+
+```bash
+vastai tfa activate --method-type totp --secret
+```
+
+Where `` is the secret token printed by this command and `` is the 6-digit code from your authenticator app.
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/reference/tfa-update.mdx b/cli/reference/tfa-update.mdx
new file mode 100644
index 00000000..3fa54700
--- /dev/null
+++ b/cli/reference/tfa-update.mdx
@@ -0,0 +1,53 @@
+---
+title: "vastai tfa update"
+sidebarTitle: "tfa update"
+---
+
+Update a 2FA method's label or primary status.
+
+## Usage
+
+```bash
+vastai tfa update METHOD_ID [--label LABEL] [--set-primary {t|true|f|false}]
+```
+
+## Arguments
+
+
+ ID of the 2FA method to update. Get the ID from `vastai tfa status`.
+
+
+## Options
+
+
+ New friendly name for this 2FA method (e.g., "Work Authenticator", "Personal Phone").
+
+
+
+ Set this method as the primary/default 2FA method. Accepts `t` or `true` to enable, `f` or `false` to disable.
+
+
+## Examples
+
+```bash
+# Rename a method
+vastai tfa update 123 --label "Personal Phone"
+
+# Set as primary/default method
+vastai tfa update 123 --set-primary t
+
+# Rename and set as primary in one command
+vastai tfa update 789 --label "Backup Authenticator" --set-primary t
+```
+
+## Global Options
+
+The following options are available for all commands:
+
+| Option | Description |
+| --- | --- |
+| `--url URL` | Server REST API URL |
+| `--retry N` | Retry limit |
+| `--raw` | Output machine-readable JSON |
+| `--explain` | Verbose explanation of API calls |
+| `--api-key KEY` | API key (defaults to `~/.config/vastai/vast_api_key`) |
diff --git a/cli/two-factor-authentication.mdx b/cli/two-factor-authentication.mdx
new file mode 100644
index 00000000..c3ddb653
--- /dev/null
+++ b/cli/two-factor-authentication.mdx
@@ -0,0 +1,183 @@
+---
+title: Two-Factor Authentication
+sidebarTitle: 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** | A 6-digit code sent to your registered email address (used as the verification channel when setting up your *first* 2FA method) |
+
+---
+
+## 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.
+
+```bash
+# 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:
+
+```bash
+vastai tfa auth-new --secret --code
+```
+
+### Step 2: Configure the method
+
+**For Authenticator App (TOTP):**
+
+```bash
+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:**
+
+```bash
+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 `.
+
+
+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
+
+```bash
+# TOTP (use the 6-digit code from your authenticator app and the secret from totp-setup)
+vastai tfa activate --method-type totp --secret
+
+# SMS (use the code received via SMS and the secret from send-sms)
+vastai tfa activate --method-type sms --secret --phone-number +12345678901
+
+# Optional: add a label
+vastai tfa activate --method-type totp --secret --label "Work Authenticator"
+```
+
+After activating your **first** 2FA method, backup codes are generated and displayed. **Save these backup codes in a secure location** — they are the only way to recover access if you lose your 2FA device.
+
+---
+
+## Logging In with 2FA
+
+If your account has 2FA enabled and your session key has expired, use `tfa login` to re-authenticate:
+
+```bash
+# 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
+
+# Email
+vastai tfa login --method-type email --code 123456 --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 this file is deleted or the session expires (returns a 404), run `tfa login` again.
+
+---
+
+## Managing Methods
+
+### View current status
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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 --code 456789
+```
+
+**Warning:** 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
+
+```bash
+# 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
+```
+
+**Warning:** 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 it expires, affected CLI commands return a 404 error. Run `vastai tfa login` to get a new session key.
+
+---
+
+## 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 code has expired | Run `vastai tfa send-sms` again to get a new code |
+| `authorization_required` | Tried to add a new 2FA method without prior authorization | Run `vastai tfa auth-new` first, then retry |
+
+---
+
+## See Also
+
+- [API Reference: Two-Factor Authentication endpoints](/api-reference/two-factor-authentication-endpoints) — REST API 2FA documentation
+- [Authentication](/cli/authentication) — API key setup and management
diff --git a/docs.json b/docs.json
index 72b5d919..389a4379 100644
--- a/docs.json
+++ b/docs.json
@@ -364,6 +364,23 @@
"cli/reference/metrics-gpu-trends",
"cli/reference/metrics-gpu-locations"
]
+ },
+ {
+ "group": "Security (2FA)",
+ "pages": [
+ "cli/two-factor-authentication",
+ "cli/reference/tfa-status",
+ "cli/reference/tfa-auth-new",
+ "cli/reference/tfa-activate",
+ "cli/reference/tfa-login",
+ "cli/reference/tfa-totp-setup",
+ "cli/reference/tfa-send-sms",
+ "cli/reference/tfa-resend-sms",
+ "cli/reference/tfa-send-email",
+ "cli/reference/tfa-regen-codes",
+ "cli/reference/tfa-update",
+ "cli/reference/tfa-delete"
+ ]
}
]
},