Jetty

Documentation for Jetty

API Tokens

API tokens (personal access tokens) authenticate the Jetty CLI and automation tools without requiring your password.

Overview

Why tokens instead of passwords:

  • Revoke individually without changing your password
  • Create separate tokens per machine, project, or CI pipeline
  • Track last-used dates for auditing
  • Scoped to a specific crew (organization)
  • Never expose your password in config files or CI systems

Creating a Token

From the Dashboard

  1. Go to Tokens (or Settings > API Tokens)
  2. Select the crew (organization) this token belongs to
  3. Enter a descriptive name (e.g., MacBook Pro - Development, GitHub Actions - Production)
  4. Configure optional settings (redaction tier, edge region, CLI server)
  5. Click Create token
  6. Copy immediately -- the token is shown only once

Naming convention: [Machine/Service] - [Project/Team/Environment]

This helps you identify which token to revoke if a machine is compromised.

Token Abilities

All tokens currently have the jetty:* ability: create/list/delete tunnels, manage settings and routing, view traffic (subject to redaction), and access organization/team resources.

Tokens inherit your permissions within the selected crew. You cannot grant more access than you personally have. Fine-grained scopes are planned for a future release.

Using Tokens with the CLI

jetty config set token YOUR_TOKEN_HERE

Stored at ~/.config/jetty/config.json (Linux/macOS) or %APPDATA%\jetty\config.json (Windows). Remove with jetty logout.

Method 2: Environment Variable

export JETTY_TOKEN=YOUR_TOKEN_HERE
jetty share 8000

Overrides config file. Required for CI/CD pipelines.

Method 3: Command-Line Flag

jetty share 8000 --token=YOUR_TOKEN_HERE

Not all commands support this flag.

Precedence Order

  1. --token= flag (highest)
  2. JETTY_TOKEN environment variable
  3. Config file
  4. No token -- authentication fails

CI/CD Integration

GitHub Actions

name: Deploy with Jetty Tunnel
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  test-with-tunnel:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Jetty CLI
        run: |
          curl -fsSL https://usejetty.online/install/jetty.sh | bash
          echo "$HOME/.local/bin" >> $GITHUB_PATH
      - name: Start tunnel
        env:
          JETTY_TOKEN: ${{ secrets.JETTY_TOKEN }}
        run: |
          jetty share 8000 --subdomain=ci-${{ github.run_id }} &
          sleep 5
      - name: Run integration tests
        run: npm test

Store the token as a repository secret: Repository > Settings > Secrets and variables > Actions.

GitLab CI

test:tunnel:
  stage: test
  variables:
    JETTY_TOKEN: $JETTY_TOKEN
  before_script:
    - curl -fsSL https://usejetty.online/install/jetty.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - jetty share 8000 --subdomain=gitlab-ci-${CI_PIPELINE_ID} &
    - sleep 5
    - ./run-tests.sh

Store the token in Settings > CI/CD > Variables. Enable Mask variable.

CI/CD Best Practices

  • Create dedicated tokens per CI system (do not reuse dev tokens)
  • Use strict redaction tier for production CI tokens
  • Use masked/protected secrets
  • Rotate tokens when team members leave or after security incidents

Token Settings

Header Redaction Tier

Controls which HTTP headers are hidden in the dashboard inspector.

  • Inherit -- Uses organization default
  • Standard -- Hides auth headers (Authorization, Cookie, API-Key, etc.)
  • Strict -- Also hides session tokens (CSRF, Session-ID, X-AMZ-Security-Token, etc.)

See the Redaction Tier Quick Start for details.

Preferred Edge Region

Available: us-east (default), us-west, eu-west, ap-southeast. Useful for distributed teams or matching CI runner location. Override per-command with --region=.

CLI Server Preference

For self-hosted or multi-instance deployments. Most users do not need this.

Security Best Practices

Do:

  • Store tokens in a password manager or CI secrets
  • One token per machine/service for easy revocation
  • Rotate every 90-180 days or after team changes
  • Revoke immediately if a machine is lost or compromised
  • Review "Last used" dates periodically

Do not:

  • Commit tokens to git
  • Share tokens between team members
  • Send tokens via email or chat
  • Reuse the same token everywhere

If a Token is Compromised

  1. Revoke immediately in the dashboard
  2. Create a replacement token
  3. Update all systems using the old token
  4. Review tunnel logs for unexpected activity
  5. Notify your team if organizational resources may be affected

Managing Tokens

Viewing Tokens

Navigate to Tokens to see all tokens with name, crew, created date, last used date, and settings badges.

Bulk Actions

The token list supports bulk operations for managing many tokens at once.

Selecting tokens:

  • Each token row has a checkbox on the left. Click individual checkboxes, or use the header checkbox to select all visible tokens.

Bulk delete:

  1. Select the tokens you want to remove.
  2. Click Delete in the action bar that appears above the list.
  3. Confirm the deletion. All selected tokens are revoked immediately.

Bulk change redaction tier:

  1. Select the tokens you want to update.
  2. Click Set Standard or Set Strict in the action bar.
  3. The redaction tier is applied to all selected tokens at once.

When to use bulk actions:

  • Cleaning up old tokens after a team reorganization
  • Standardizing redaction tier across all CI/CD tokens
  • Revoking all tokens for a decommissioned machine or service

Revoking Tokens

Go to Tokens, find the token, click Revoke. The token immediately stops working. Active tunnels remain connected until closed; new API calls with that token fail.

Regenerating Tokens

Jetty does not support regenerating tokens in place. Instead: create a new token, update your config, test, then revoke the old token.

Team Context

All tokens are personal access tokens scoped to a specific crew. A token for "Engineering Team" can only access Engineering Team resources.

To switch teams from the CLI:

# Option 1: Create separate tokens per crew, switch config
jetty config set token ENGINEERING_TOKEN

# Option 2: Use environment variables
JETTY_TOKEN=$ENGINEERING_TOKEN jetty share 8000

# Option 3: Shell aliases
alias jetty-eng='JETTY_TOKEN=$ENGINEERING_TOKEN jetty'

Troubleshooting

"Invalid token"

  • Token may have been revoked -- check Tokens page
  • Ensure you copied the full token (format: 1|a2b3c4d5e6f...)
  • Verify the token matches your Jetty instance (staging vs production)
  • Check for typos: jetty config get token or echo $JETTY_TOKEN

Token Not Working in CI

  1. Verify the secret is set correctly in your CI platform
  2. Check that the token still exists and has not been revoked
  3. Ensure JETTY_TOKEN (not JETTY_API_TOKEN) is the variable name
  4. Test the token locally first: JETTY_TOKEN=your_ci_token jetty share 8000

Permissions Issues (403 / "No team context")

  • Token may lack organization context -- create a new one with a crew selected
  • You may have been removed from the team
  • Token may be scoped to a different crew

Tunnels in Wrong Team

The token determines team context. Check which crew your token belongs to in the dashboard, then create a new token for the correct crew if needed.

Quick Reference

jetty config set token YOUR_TOKEN    # Save token
jetty config get token               # Check saved token
jetty logout                         # Remove saved token
JETTY_TOKEN=xxx jetty share 8000     # Use without saving

Next Steps

Need help? Contact Jetty support or check the dashboard for organization-specific documentation.

Send feedback

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