Jetty

Documentation for Jetty

Two-Factor Authentication (2FA)

Overview

Two-factor authentication (2FA) adds an essential extra layer of security to your Jetty account by requiring two forms of verification:

  1. Something you know: Your password
  2. Something you have: Your phone with an authenticator app

Why Enable 2FA?

Without 2FA, anyone who obtains your password can access your Jetty account, including:

  • Your active tunnels and their configuration
  • Team settings and member management
  • API tokens and authentication credentials
  • Usage history and logs

With 2FA enabled, even if your password is compromised, attackers cannot access your account without also having access to your physical device.

Security Benefits

  • Protection against password theft: Stolen passwords alone cannot access your account
  • Defense against phishing: Even if tricked into entering your password, the attacker lacks your second factor
  • Compliance ready: Many security frameworks require 2FA for privileged accounts
  • Peace of mind: Know your tunnels and data are secure even if credentials leak

Enabling Two-Factor Authentication

Step 1: Navigate to Security Settings

  1. Log in to your Jetty dashboard at https://usejetty.online
  2. Click your profile icon in the top-right corner
  3. Select Settings from the dropdown menu
  4. Navigate to the Security tab
  5. Find the Two-Factor Authentication section
  6. Click Enable Two-Factor Authentication

Step 2: Choose Authenticator App

Jetty uses Time-based One-Time Password (TOTP) authentication, which is supported by all major authenticator apps:

Recommended Apps:

  • Google Authenticator (iOS, Android) - Simple and reliable
  • Authy (iOS, Android, Desktop) - Multi-device sync and backup
  • 1Password (All platforms) - Integrated with password manager
  • Bitwarden (All platforms) - Open-source with password manager integration
  • Microsoft Authenticator (iOS, Android) - Push notifications and multi-account support

Choose an app you already use or download one from your device's app store before proceeding.

Step 3: Scan QR Code

Once you click to enable 2FA:

  1. A QR code will appear on your screen
  2. Open your authenticator app
  3. Select Add Account or Scan QR Code (varies by app)
  4. Point your camera at the QR code displayed in Jetty

Can't scan the code? Most apps let you enter a setup key manually. Click "Can't scan? Enter key manually" to reveal the text-based setup key.

Your authenticator app will immediately begin generating 6-digit codes that refresh every 30 seconds.

Step 4: Save Recovery Codes

This is the most critical step. After scanning the QR code, Jetty will display 10 recovery codes.

Recovery Codes:
a1b2-c3d4-e5f6
g7h8-i9j0-k1l2
m3n4-o5p6-q7r8
s9t0-u1v2-w3x4
y5z6-a7b8-c9d0
e1f2-g3h4-i5j6
k7l8-m9n0-o1p2
q3r4-s5t6-u7v8
w9x0-y1z2-a3b4
c5d6-e7f8-g9h0

Important:

  • Each recovery code can only be used once
  • Without these codes, if you lose access to your authenticator app, you cannot access your account
  • Download and save these codes immediately (a download button is provided)

Storage recommendations (see Storing Securely below):

  • Save to a password manager (1Password, Bitwarden, LastPass)
  • Print and store in a secure physical location
  • Store in an encrypted note or secure vault
  • Never email them to yourself or store in plain text files

Step 5: Confirm Setup

To complete setup:

  1. Enter one of the 6-digit codes from your authenticator app
  2. The code is time-sensitive (valid for 30 seconds)
  3. Click Verify and Enable 2FA

If the code is accepted:

  • Two-factor authentication is now active
  • Your account requires 2FA for all future logins
  • Keep your authenticator app accessible

Using 2FA

Logging In

Once 2FA is enabled, your login flow changes:

  1. Enter your email and password as usual
  2. Click Sign In
  3. New: A 2FA verification screen appears
  4. Open your authenticator app and find your Jetty account
  5. Enter the current 6-digit code
  6. Click Verify

The code refreshes every 30 seconds. If a code expires while you're entering it, simply wait for the new code to appear and use that instead.

CLI Authentication

The jetty CLI respects 2FA for authentication flows:

Browser-Based Authentication (OAuth)

When you run jetty login with 2FA enabled:

jetty login
  1. The CLI opens your browser to complete authentication
  2. You'll be prompted for your password
  3. Then prompted for your 2FA code
  4. After successful 2FA verification, the CLI receives the authentication token
  5. You're now authenticated in the CLI

API Token Authentication

API tokens bypass 2FA (since they're already secured credentials):

export JETTY_API_TOKEN="your-token-here"
jetty share

Security note: Protect API tokens with the same care as passwords. Anyone with a valid API token can use Jetty CLI as you, even with 2FA enabled on your account.

Browser Authentication Flow

When authenticating the CLI via browser (OAuth flow) with 2FA enabled:

  1. CLI initiates OAuth: jetty login
  2. Browser opens to Jetty dashboard
  3. You log in with email and password
  4. 2FA prompt appears - enter authenticator code
  5. After successful 2FA, you authorize the CLI application
  6. Browser redirects back with success message
  7. CLI receives and stores authentication token

This flow ensures that even CLI authentication benefits from your 2FA protection.

Recovery Codes

What Are Recovery Codes?

Recovery codes are one-time-use backup codes that can be used instead of your authenticator app code. Each code:

  • Is unique and randomly generated
  • Can be used only once
  • Works exactly like an authenticator code at the 2FA prompt
  • Bypasses the need for your authenticator app

You receive 10 recovery codes when you first enable 2FA.

When to Use Recovery Codes

Use a recovery code when you cannot access your authenticator app:

Common scenarios:

  • Lost or broken phone - Device with authenticator is unavailable
  • Switching devices - Getting new phone and haven't transferred authenticator yet
  • Deleted authenticator app - Accidentally removed the app or the Jetty account from it
  • Emergency access - Need to log in urgently without your primary device

How to Use a Recovery Code

  1. At the 2FA prompt after entering your password
  2. Click "Use a recovery code instead"
  3. Enter one of your saved recovery codes exactly as shown (with or without dashes)
  4. Click Verify

The code is immediately consumed and cannot be reused.

After using a recovery code:

  • Re-enable your authenticator app as soon as possible
  • Generate new recovery codes to replace used ones

Storing Securely

Recovery codes are sensitive and grant access to your account. Store them with the same security as your password.

Recommended storage methods:

  • Password Manager: Store in 1Password, Bitwarden, LastPass (same place as your Jetty password)
  • Encrypted Notes: Use OS-native encrypted storage (Keychain on macOS, encrypted notes)
  • Printed Copy: Print and store in a locked safe or secure drawer at home
  • Secure Cloud Storage: Encrypted cloud notes (Apple Notes, encrypted Google Drive folder)

Avoid these insecure methods:

  • Unencrypted text files on your desktop
  • Email to yourself
  • Slack or chat messages to yourself
  • Screenshots saved to auto-syncing photo libraries
  • Sticky notes or unprotected documents

Best practice: Use your password manager. Most apps have a "notes" field for each entry - store recovery codes there alongside your Jetty password.

Regenerating Codes

You should regenerate recovery codes when:

  • You've used several codes and have few remaining
  • You suspect your codes may have been compromised
  • You want to invalidate all existing codes

To regenerate recovery codes:

  1. Log in to Jetty dashboard
  2. Navigate to Settings → Security
  3. In the Two-Factor Authentication section, click View Recovery Codes
  4. Enter your current password to confirm
  5. Click Regenerate Recovery Codes
  6. Warning: This invalidates all previous codes
  7. Save the new codes immediately

Important: After regeneration, all old recovery codes stop working. Update your password manager or wherever you stored the old codes.

Disabling 2FA

You can disable two-factor authentication, but this reduces your account security.

When to Disable

Consider disabling 2FA only if:

  • You've permanently lost access to both your authenticator app and all recovery codes
  • You're coordinating with Jetty support on an account recovery
  • You're migrating to a different 2FA method (disable, then re-enable with new setup)

In most cases, you should keep 2FA enabled and regenerate recovery codes if needed.

How to Disable

  1. Log in to your Jetty dashboard (requires 2FA)
  2. Navigate to Settings → Security
  3. In the Two-Factor Authentication section, click Disable 2FA
  4. Confirm with your password - Enter your account password
  5. Confirm with authenticator code or recovery code - Enter a valid 2FA code
  6. Click Confirm Disable

After disabling:

  • Your account returns to password-only authentication
  • All recovery codes are invalidated
  • Your authenticator app entry can be removed (or kept for when you re-enable)

Security warning: Your account is now more vulnerable to password theft. Consider re-enabling 2FA as soon as possible.

Troubleshooting

"Invalid Code" Errors

If your authenticator code is consistently rejected:

Time Sync Issues (Most Common)

Authenticator codes are time-based. If your device clock is off by even 30 seconds, codes won't work.

Fix:

  1. Check your phone's time settings
  2. Enable automatic time and date (sync with network)
  3. Ensure you're in the correct timezone
  4. Restart your authenticator app
  5. Wait for a fresh code to generate
  6. Try again

Testing: If the code works after time sync, this was the issue.

Wrong App or Account Selected

If you use your authenticator for multiple services:

Fix:

  1. Open your authenticator app
  2. Confirm you're looking at the Jetty entry (not another service)
  3. Verify the account email matches your Jetty account
  4. Check if you have multiple Jetty entries (perhaps from a previous setup)
  5. Use the entry that was created during your most recent 2FA setup

Recent Setup Timing

Immediately after setup, there can be a brief sync delay:

Fix:

  1. Wait for the current code to expire
  2. Let a fresh code generate (wait 30 seconds)
  3. Use the new code

App-Specific Issues

Some authenticator apps have quirks:

Google Authenticator:

  • Doesn't sync between devices - ensure you're using the device where you scanned the QR code
  • No backup - if you uninstalled and reinstalled, you need to set up 2FA again

Authy:

  • Verify you're logged into the correct Authy account
  • If using desktop and mobile, ensure they're synced

1Password:

  • Ensure you're viewing the correct vault
  • Check if there are multiple Jetty entries

Lost Phone Without Recovery Codes

This is the most serious scenario: you cannot access your authenticator app and you don't have any recovery codes.

Account recovery process:

  1. Contact Jetty Support: Email support with your account details

    • Your registered email address
    • Account name or team name
    • Any other identifying information

  2. Verify your identity: Support will ask for verification:

    • Access to your registered email address
    • Previous login locations or activity
    • API tokens or other account details you may have saved
    • Payment information if applicable

  3. Await manual review: For security, this process takes time (typically 24-48 hours)

  4. 2FA reset: Once verified, support will disable 2FA on your account

  5. Immediate re-enablement: After regaining access, immediately re-enable 2FA and save your new recovery codes

Prevention is key: This recovery process can be avoided by securely storing recovery codes when you first enable 2FA.

Time Synchronization

Time sync is critical for TOTP codes. Check your device settings:

iOS:

  1. Settings → General → Date & Time
  2. Enable Set Automatically
  3. Restart your device if you changed this setting

Android:

  1. Settings → System → Date & Time
  2. Enable Use network-provided time
  3. Enable Use network-provided time zone
  4. Restart your device if you changed this setting

Computer (for web login):

  • Ensure your computer's system time is also correct
  • Browser time comes from system time, which affects the server's validation window

After fixing time sync, wait for a new code cycle (30 seconds) before attempting login.

Security Best Practices

Follow these practices to maximize your account security:

1. Use a Reliable Authenticator App

Choose an authenticator app that:

  • Is actively maintained and updated
  • Has good reviews and reputation
  • Supports backup/sync if you want multi-device access (Authy, 1Password)
  • Fits your workflow (standalone app vs. password manager integration)

Recommended: 1Password or Bitwarden if you already use them for passwords. Otherwise, Google Authenticator or Authy.

2. Store Recovery Codes Securely

  • Always save recovery codes when first enabling 2FA
  • Store in your password manager alongside your Jetty password
  • Consider printing a copy for a safe or secure drawer
  • Treat recovery codes with the same security as your password
  • Regenerate codes periodically (every 6-12 months) or after use

3. Don't Share Codes

  • Never share authenticator codes or recovery codes with anyone
  • Jetty support will never ask for your 2FA codes
  • Be wary of phishing attempts that request codes
  • Each code is single-use and time-sensitive

4. Enable for All Team Owners

If you manage teams:

  • Strongly recommend or require 2FA for all team owners
  • Team owners have elevated privileges (member management, billing, settings)
  • A compromised owner account can affect the entire team
  • Lead by example - enable it on your own account first

5. Keep Your Authenticator App Secure

  • Use a device PIN/passcode or biometric lock
  • Don't root/jailbreak your device (reduces security)
  • Keep your OS and authenticator app updated
  • Back up authenticator data if your app supports it (Authy, 1Password)

6. Use API Tokens Carefully

  • API tokens bypass 2FA (since they're pre-authenticated credentials)
  • Store tokens as securely as passwords
  • Use environment variables, not hardcoded values
  • Rotate tokens periodically
  • Revoke tokens you no longer use

7. Monitor Account Activity

  • Review active sessions in your dashboard regularly
  • Log out sessions you don't recognize
  • Check for unexpected API tokens
  • Monitor tunnel activity logs for suspicious traffic

8. Prepare for Device Loss

Before you lose access:

  • Save recovery codes now (don't wait until you need them)
  • Consider using an authenticator with cloud sync (Authy, 1Password)
  • Document your recovery process (where codes are stored)
  • Test recovery codes occasionally to ensure they work

Team Considerations

Understanding how 2FA works in team environments:

2FA is Per-User, Not Per-Team

Two-factor authentication is tied to your personal Jetty account, not to teams:

  • Each user enables 2FA individually for their own account
  • 2FA protects your credentials when accessing any team
  • You don't enable 2FA "for a team" - you enable it for yourself
  • One 2FA setup protects all teams you're a member of

Team Owner Recommendations

If you're a team owner:

Strongly consider requiring 2FA for:

  • All team owners (who have full team control)
  • Users with sensitive tunnel access
  • Users handling production tunnels
  • Any privileged team roles

How to encourage adoption:

  • Lead by example - enable 2FA on your account
  • Share this documentation with your team
  • Explain the security benefits clearly
  • Provide time for team members to set up 2FA
  • Offer support for team members during setup

Note: Jetty does not currently enforce 2FA at the team level, but you can make it a team policy and verify during security reviews.

Team Member 2FA Status

As a team owner, you cannot:

  • See whether team members have 2FA enabled (privacy)
  • Force team members to enable 2FA (they control their accounts)
  • Reset another user's 2FA (only Jetty support can assist with account recovery)

Best practice: Include 2FA enablement as part of team onboarding and periodic security check-ins.

Service Accounts and Automation

For automated systems using Jetty:

  • Use API tokens for authentication (these bypass 2FA)
  • Store tokens in secure secret management (environment variables, vault)
  • Use service-specific tokens, not personal user tokens
  • Rotate tokens periodically
  • Revoke tokens when services are decommissioned

Tunnel Access with 2FA

Enabling 2FA on your account does not affect:

  • Active tunnel functionality (tunnels keep running)
  • CLI commands using API tokens
  • Webhook or API integrations
  • Programmatic access with valid tokens

2FA only affects:

  • Web dashboard login
  • OAuth-based CLI login (jetty login)
  • Any authentication flow requiring your password

Additional Resources

Need Help?

If you encounter issues not covered in this guide:

  • Documentation: Browse other guides in docs/user-guides/
  • Support: Contact Jetty support with your account details
  • Community: Join our community channels for peer assistance

Enabling 2FA protects your Jetty account, tunnels, and team data. The few extra seconds during login are worth the security improvement.

Send feedback

Found an issue or have a suggestion? Let us know.