Teams and Organizations

Collaborate with your crew. Jetty's teams and organizations let you share tunnels, manage access, and work together—all within a single billing and security boundary.

Overview

What are Organizations and Teams?

Jetty uses a two-tier structure for collaboration:

• Organizations — The top-level entity. Organizations own billing, settings, and security policies. Think of an organization as your company, agency, or personal workspace.
• Teams — Groups within an organization. Teams own tunnels, reserved subdomains, and custom domains. Most day-to-day work happens at the team level.

Example hierarchy:

Acme Corp (Organization)
├── Engineering Team
│   ├── Alice (owner)
│   ├── Bob (member)
│   └── Tunnels: api-staging, frontend-dev
├── Design Team
│   ├── Carol (admin)
│   └── Tunnels: design-preview
└── QA Team
    └── Dave (member)

Why use teams?

• Separate projects — Keep production tunnels isolated from experimental ones
• Manage access — Grant different people access to different teams
• Track usage — See which team is using what resources
• Organize work — Group related tunnels and domains together

Plans and limits

• Harbor (free) — Personal workspace with one default team
• Coastal — Multiple teams, team invitations, and collaboration features
• Fleet — Everything in Coastal, plus higher limits

Teams are essential for paid plans. See Bridge → Billing for your current plan.

Creating Your First Team

When you register, Jetty automatically creates:

1. A personal organization (e.g., "Alice's Organization")
2. A default team within that org (e.g., "Alice's Team")
3. You're the owner of both

Creating an additional team

Dashboard:

1. Navigate to Organization → Teams
2. Click Create Team
3. Enter a team name (e.g., "Staging Environment")
4. Click Create

![Screenshot: Create Team dialog]

What happens:

• The new team appears in your teams list
• You're automatically added as the team owner
• The team inherits your organization's settings
• You can now create tunnels scoped to this team

API:

curl -X POST https://usejetty.online/api/organization/teams \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging Environment"}'

Team Roles

Jetty has roles at two levels: organization and team.

Organization roles

Set in Organization → Members:

Team roles

Set in Team → Members for that specific team:

How roles interact

• Org owners and admins automatically get Owner permissions on all teams in the organization
• Team owners can only manage their specific team
• Managers can manage tunnels and resources but cannot add or remove team members
• Developers can create and use HTTP tunnels but need Manager+ for TCP/UDP tunnels or domain management
• Viewers can monitor but cannot create or modify anything
• You can be an owner on one team and a developer on another

Example: Alice is an org admin and a member of the Engineering team. She can invite Bob to the organization and add him to any team, but she doesn't need to be a team owner to do so.

Inviting Team Members

Prerequisites

• You must be an org owner/admin or team owner to send invitations
• Your organization must have available seats (if seat limits apply to your plan)
• The invitee needs a valid email address

Send an invitation

Dashboard:

1. Go to Organization → Teams
2. Select the team
3. Click Team Members or the members icon
4. Click Invite Member
5. Enter their email address
6. Choose their team role (owner, admin, or member)
7. Click Send Invitation

![Screenshot: Invite Team Member form]

What the recipient receives:

The invitee gets an email with:

• Your name and organization name
• The team they're invited to
• Their assigned role
• An invitation link (valid for 7 days by default)

Email example:

Subject: You've been invited to join Acme Corp on Jetty

Hi,

Alice invited you to join the Engineering Team in Acme Corp's Jetty workspace.

Your role: Member

Accept invitation: https://usejetty.online/invitations/abc123xyz

This invitation expires in 7 days.

Accepting an invitation

For new users:

1. Click the invitation link
2. Sign up for a Jetty account (if you don't have one)
3. After registration, you're automatically added to the team

For existing users:

1. Click the invitation link
2. Sign in to your Jetty account
3. Review the invitation details
4. Click Accept Invitation
5. You're added to the team and can switch to it immediately

Dashboard feedback:

After accepting, you'll see:

• The new team in your team switcher
• Access to that team's tunnels and settings
• A notification confirming you joined

Managing Team Members

View team members

Dashboard:

1. Go to Organization → Teams
2. Click on the team name
3. View the Members tab

You'll see:

• Each member's name and email
• Their team role
• When they joined

![Screenshot: Team Members list]

Change a member's role

Requirements: You must be an org admin or team owner

Steps:

1. Navigate to Team → Members
2. Find the member
3. Click the role dropdown next to their name
4. Select the new role (owner, admin, or member)
5. Confirm the change

What happens:

• The change takes effect immediately
• The member sees updated permissions when they reload
• An audit log entry is created (if audit logging is enabled)

Remove a member from a team

Requirements: You must be an org admin or team owner

Steps:

1. Navigate to Team → Members
2. Find the member
3. Click Remove or the trash icon
4. Confirm the removal

What happens:

• The member loses access to this team's tunnels
• They remain in the organization (unless this was their last team)
• Active tunnels they created are stopped
• Reserved subdomains they own are released

Note: If you remove a member from their last team in the organization, they're automatically removed from the organization entirely.

Remove a member from the organization

Requirements: You must be an org owner or org admin

Steps:

1. Navigate to Organization → Members
2. Find the member
3. Click Remove from Organization
4. Confirm the removal

What happens:

• The member is removed from all teams in the organization
• They lose access to all tunnels, subdomains, and custom domains
• Any API tokens scoped to this organization are invalidated
• They keep their Jetty account (and any other organizations they belong to)

Switching Between Teams

Users who belong to multiple teams can switch contexts in the dashboard.

Use the team switcher

Location: Top navigation bar, next to your profile

![Screenshot: Team switcher dropdown]

Steps:

1. Click the current team name in the top nav
2. A dropdown appears with all your teams
3. Click the team you want to switch to
4. The dashboard reloads with that team's context

What changes:

• Tunnels page shows only that team's tunnels
• Domains page shows only that team's reserved subdomains and custom domains
• Team settings are specific to the selected team
• API tokens created while this team is active are scoped to this team

Team context in the CLI

When you create an API token in the dashboard, it's scoped to your currently selected team.

# Token created while "Engineering Team" was selected
jetty config set token YOUR_TOKEN_HERE

# This tunnel belongs to Engineering Team
jetty share 8000

To use a different team from the CLI:

1. Switch teams in the dashboard
2. Create a new API token (scoped to the new team)
3. Update your CLI config:

   jetty config set token NEW_TOKEN_FOR_OTHER_TEAM
   

Pro tip: Use shell aliases or environment variables to manage multiple tokens:

# ~/.bashrc or ~/.zshrc
export JETTY_TOKEN_ENG="token_abc123..."
export JETTY_TOKEN_STAGING="token_xyz789..."

# Then use
jetty config set token "$JETTY_TOKEN_ENG"
jetty share 8000

Team Settings

Settings are scoped at two levels: organization and team.

Organization-level settings

Apply to all teams in the organization. Managed in Organization → Settings.

Examples:

• Billing plan (Harbor, Coastal, Fleet)
• Header redaction tier (what gets logged in request samples)
• Tunnel inspection enabled/disabled
• Notification preferences (Telegram, email)
• Tunnel local host allowlist (security: which IPs can be used as upstream targets)

Who can change: Org owners and admins

Compliance presets

Organization settings include one-click compliance presets for common regulatory frameworks. Navigate to Organization --> Settings --> Compliance to apply a preset.

Available presets:

Each preset sets the redaction tier, blocked header list, sample limits, and host allowlist to values appropriate for that framework. You can review and adjust individual settings after applying a preset.

Applying a preset: Select the preset from the dropdown and click Apply. Existing settings are overwritten by the preset values.

Clearing a preset: Click Clear compliance preset to remove the preset label. The individual settings remain at their current values -- they are not reset to defaults automatically.

Settings export and import

You can export your organization's settings as a JSON file for backup or to replicate the configuration across organizations.

Export: Click Export Settings in Organization --> Settings. This downloads a JSON file containing: redaction tier, sample limits, host allowlist, routing rule limits, compliance preset, and notification preferences.

Import: Click Import Settings and paste or upload a previously exported JSON file. The imported values overwrite current settings. Review the confirmation dialog before applying.

This is useful for agencies managing multiple client organizations with the same security and compliance policies.

Team-level settings

Specific to each team. Managed in Team → Settings.

Examples:

• Team name and slug
• Reserved subdomains (which labels this team has claimed)
• Custom domains (DNS-verified hostnames for this team's tunnels)
• Team members and roles

Who can change: Org admins and team owners

Personal settings

Apply only to you, not other team members. Managed in Profile → Settings.

Examples:

• Your name and email
• Notification preferences (do you get emailed for tunnel events)
• API tokens (personal vs team-scoped)
• CLI defaults (server name, preferred region)

Best Practices

When to create new teams vs use existing

Create a new team when:

• You have a distinct project or environment (e.g., "Mobile App Dev" vs "Web App Dev")
• You need different people to access different tunnels
• You want to separate staging/production tunnels
• You're managing multiple clients (agencies: one team per client)

Use an existing team when:

• The work is closely related and the same people need access
• You want to keep things simple (fewer teams = easier to manage)
• You're on the free plan (one team maximum)

Role assignment strategies

Recommended patterns:

1. Small teams (2-5 people):

   • One org owner (company owner or tech lead)
   • Everyone else as team owners (full autonomy)
   • Add members only if you need to restrict permissions

2. Medium teams (6-20 people):

   • One org owner (billing and ultimate control)
   • 1-2 org admins (team leads or senior engineers)
   • Team owners for each project/team lead
   • Most engineers as team members

3. Large teams or agencies (20+ people):

   • One org owner (business owner)
   • Multiple org admins (department heads)
   • Team owners for project managers
   • Team members for individual contributors
   • Consider separate organizations for completely independent business units

Principle of least privilege:

Start with member role and promote to admin/owner only when needed. It's easier to grant permissions later than to clean up after over-permissioned accidents.

Naming conventions

Organizations:

• Use your company or personal name: "Acme Corp", "Alice's Workspace"
• Avoid abbreviations that will confuse new members

Teams:

• Be descriptive: "Frontend Dev", "Staging Environment", "Client: Acme"
• Include environment if relevant: "API Production", "Mobile Staging"
• Use consistent prefixes for related teams: "Project Alpha - Dev", "Project Alpha - QA"

Reserved subdomains:

• Include team context: acme-api-staging, frontend-dev-alice
• Avoid generic names like test, app, web (they'll conflict)
• Use the project or feature name: checkout-flow, oauth-callback

Notification preferences

Organizations can configure where event notifications are delivered. Navigate to Organization --> Settings --> Notifications to set up notification routing.

Event types:

Channels:

• Email -- Sent to the organization owner and admins
• Telegram -- Sent to a connected Telegram chat (configure bot token and chat ID in settings)
• Webhook -- POST a JSON payload to a URL you specify

The settings page shows a toggle grid where you can enable or disable each event type per channel. For example, you might send tunnel_down to Telegram and webhook but only billing_failure to email.

Defaults: When no notification preferences are configured, billing_failure and security_alert are sent to the organization owner's email. All other events are off by default.

Security hygiene

1. Review members regularly — Remove people who left the project
2. Use team roles, not org roles — Don't make everyone an org admin
3. Rotate API tokens — Regenerate tokens if someone leaves
4. Set header redaction — Use aggressive tier for production tunnels
5. Monitor audit logs — Check who's doing what (Coastal/Fleet plans)

Troubleshooting

"You don't have permission to perform this action"

Causes:

• You're a member trying to invite someone (need admin or owner)
• You're on a team trying to change org settings (need org admin)
• You're trying to manage billing as a member (need org owner or admin)

Solution:

1. Check your role: Profile → Teams or Organization → Members
2. Ask an org admin or team owner to grant you the appropriate role
3. If you're the only person, check that you're viewing the correct organization (switch orgs if you have multiple)

"This invitation has expired"

Cause: Invitations are valid for 7 days (configurable by operators)

Solution:

1. Ask the person who invited you to resend the invitation
2. Check your email for a more recent invitation
3. If you're the inviter: Organization → Teams → [Team] → Members → Invite again

"No seats available"

Cause: Your organization has a seat limit (Coastal/Fleet plans can set this) and you've reached the maximum

Solutions:

• Remove inactive members to free up seats
• Upgrade your plan to increase the seat limit
• Contact billing to purchase additional seats (if your plan supports it)
• Check for duplicate accounts (same person with multiple emails)

"Cannot remove the last owner"

Cause: Every team and organization must have at least one owner

Solution:

1. Promote another member to owner first
2. Then remove yourself or the other owner
3. If you want to delete the team: Organization → Teams → [Team] → Delete Team

Team switcher shows the wrong team

Cause: Your browser cached the old team selection, or you logged in after switching teams

Solution:

1. Refresh the page (hard refresh: Cmd+Shift+R or Ctrl+F5)
2. Switch teams manually using the team switcher
3. Clear browser cache if the problem persists
4. Sign out and sign in as a last resort

CLI tunnels appear in the wrong team

Cause: Your API token is scoped to a different team than you intended

Solution:

1. Switch to the correct team in the dashboard
2. Create a new API token (it will be scoped to the currently selected team)
3. Update your CLI config:

   jetty config set token NEW_TOKEN_HERE
   

4. Verify by creating a test tunnel and checking the dashboard

Can't see a team I was invited to

Causes:

• You didn't accept the invitation yet
• The invitation expired before you clicked it
• You accepted the invitation while logged in to a different account

Solutions:

1. Check your email for the invitation link and click it
2. Sign out and sign in to the account that received the invitation
3. Contact the person who invited you to resend the invitation
4. Check spam folder — invitation emails sometimes get filtered

Organization member can't create tunnels

Causes:

• They're an org member but not added to any team yet
• The team they're on doesn't have tunnel creation permissions (shouldn't happen, but check roles)
• Their API token is expired or invalid

Solutions:

1. Org admin: Add them to a team via Organization → Teams → [Team] → Members → Add
2. Check their team role: Ensure they're at least a member (not just invited)
3. Have them regenerate their API token in Profile → API Tokens
4. Verify their token has the right permissions: scoped to a team they belong to

Related Documentation

• Installation — Set up the jetty CLI
• Sharing Local Sites — Create your first tunnel
• Tunnels Reference — Complete tunnel feature guide
• Quick Reference: ENV to Database — Organization settings overview

Next Steps

1. Create your first additional team if you're collaborating
2. Invite a team member to test the flow
3. Create a tunnel scoped to your new team
4. Switch between teams to see how context changes
5. Set up reserved subdomains for stable webhook URLs

Questions? Check the Troubleshooting section above or contact support.