Authentication

Dashboard authentication

Users log into hle.world/dashboard using one of these methods:

• Email & password: Register a new account with email and password
• GitHub SSO: OAuth 2.0 via GitHub
• Google SSO: OIDC via Google

API keys

API keys authenticate the client tunnel to the relay server. Key details:

• Format: hle_ prefix + 32 hex characters (36 chars total)
• Stored as: SHA-256 hash in the database (plaintext never stored)
• Per-key tunnel limit: Each key has a max_tunnels cap that matches your plan tier — Free: 2, Pro: 5, Business: 15. The limit is enforced automatically when you upgrade or downgrade.
• Created in: Dashboard > Keys
• Visible once: The raw key is only shown once on creation — save it immediately

Tunnel authentication flow

1. Client sends TUNNEL_REGISTER message with api_key
2. Server hashes the key and looks up ApiKeyRecord
3. Server validates:
   • Key exists and is active
   • Tunnel count does not exceed max_tunnels
4. Server derives user_code from key owner’s UserRecord (3-char alphanumeric)
5. Tunnel is registered with format: <service_label>-<user_code>.<base_domain>

Tip

WebSocket close codes: If authentication fails, the server closes the WebSocket with a specific code:

• 4001 = invalid or missing API key
• 4003 = tunnel limit exceeded

Subdomain routing

Each tunnel gets a unique public URL:

<service_label>-<user_code>.hle.world

Example: If your user code is x7k and label is ha, the URL is https://ha-x7k.hle.world

• user_code: Server-allocated 3-char alphanumeric per user, derived from API key owner
• service_label: User-chosen name (e.g., “ha”, “jellyfin”, “app1”), auto-generated if omitted

Tunnel access control

For each tunnel, the owner can create an email allow-list with provider selection from the tunnel’s Access Control tab in the dashboard. Provider options:

• any: Allow any auth method (native email/password, GitHub, Google)
• github: Require GitHub SSO
• google: Require Google SSO
• hle: Require native HLE email/password login

When a user accesses the tunnel gate page, only the allowed auth methods are displayed:

• provider: "github" — Only GitHub button shown
• provider: "any" — All buttons (email form, GitHub, Google)

PIN protection

In addition to the email allow-list, any tunnel can be protected with a PIN. Visitors who pass the SSO gate are then prompted for the PIN before being granted access. PIN protection is available on all plans and is configured from the tunnel’s Access Control tab in the dashboard.

HTTP Basic Auth

Any tunnel can be protected with standard HTTP Basic Auth — a username and password enforced by the relay before the request ever reaches your local service. This works natively with browsers (which show a credentials dialog), curl, and any HTTP client that understands Authorization: Basic.

Tip

How it works: When Basic Auth is enabled on a tunnel, the relay checks the Authorization: Basic header on every incoming request. Missing or invalid credentials return 401 Unauthorized with a WWW-Authenticate: Basic header. Valid credentials grant access immediately — no SSO gate or cookie needed. Basic Auth takes priority over PIN and email allow-list.

Configure it from the tunnel’s Access Control tab in the dashboard, or via the CLI:

hle basic-auth set myapp-x7k     # prompts for username & password
hle basic-auth status myapp-x7k  # show whether active
hle basic-auth remove myapp-x7k  # remove credentials

Credentials are stored as PBKDF2-SHA256 hashes. The password is never returned in plaintext.

Upstream Basic Auth

Separately, you can inject Basic Auth credentials into every request forwarded to your local service. This is useful when the local service itself requires authentication (e.g., Home Assistant, Grafana, or Jupyter):

hle expose --service http://localhost:8123 --upstream-basic-auth admin:yourpassword

This injects an Authorization: Basic header on every proxied request — independent of the tunnel-level Basic Auth above.

Share links

Share links let you grant temporary access to a tunnel without adding someone to the permanent allow-list. Each share link embeds a signed token that is validated at the gate:

• Free: links valid up to 1 hour, 1 active at a time
• Pro: links valid up to 24 hours, up to 10 active
• Business: links valid up to 7 days, unlimited active

Share links are created from the tunnel’s Share Links tab in the dashboard.

CLI authentication

The CLI commands (hle tunnels, hle access) authenticate against the REST API using your API key sent as an Authorization: Bearer header. The key is resolved in this order:

1. --api-key command-line flag
2. HLE_API_KEY environment variable
3. ~/.config/hle/config.toml config file

The same API key used for tunnel connections also authenticates REST API calls for managing access rules and listing tunnels. The dashboard uses JWT cookies for the same endpoints — both auth methods are accepted.

JWT tokens

JWT tokens are issued by the server and stored in HTTP-only, SameSite=Lax cookies. The secure flag is set automatically — cookies are marked secure in production (HTTPS) and plain in local development (HTTP).

• Dashboard JWT (hle_access_token): 24h expiry, used for all /api/* dashboard endpoints
• Tunnel access JWT (hle_tunnel_token): 24h expiry, issued after a visitor passes the SSO gate page, scoped to the specific tunnel subdomain

Password security

Passwords are hashed using PBKDF2-SHA256 with 600,000 iterations. This is OWASP-recommended and resistant to modern GPU attacks.

Rate limiting

Authentication endpoints are rate-limited to prevent brute force attacks. The limit is applied per IP address across the hle.world hosted service.