Authentication

Authentication is off by default. No tokens are generated, and all requests pass through without credentials. This is fine for local-only setups.

When you expose your server to a network or the internet, enable authentication to restrict access.

Enable Authentication

Set a single environment variable in ~/.jean2/.env (or your shell environment):

JEAN2_AUTH_TOKEN=your-secret-token

Restart the server after changing this value:

jean2 restart

When set, all API and WebSocket endpoints require the token. When not set, all requests pass through without authentication.

Authenticating Requests

When auth is enabled, clients must provide the token via one of two methods:

HTTP header:

Authorization: Bearer your-secret-token

Query parameter:

?token=your-secret-token

Both methods work for REST and WebSocket connections. The desktop and web clients handle this automatically — you enter the token once when adding a server connection.

Client Configuration

When connecting a desktop or web client to a server with auth enabled:

1. Open the client settings
2. Enter the server URL
3. Enter the token (the value you set in JEAN2_AUTH_TOKEN)
4. Connect

The client stores the token securely and includes it with every request.

Security Considerations

• Local-only setups — auth is unnecessary if the server is only accessible from localhost
• Network exposure — always enable auth when the server is reachable from other machines
• TLS — combine auth with TLS for encrypted communication
• Reverse proxies — if using a reverse proxy, the proxy handles TLS termination; auth still protects the API endpoints
• Token rotation — change the JEAN2_AUTH_TOKEN value and restart the server to rotate tokens

Environment Variables

Variable	Default	Description
JEAN2_AUTH_TOKEN	(unset)	When set, all endpoints require this token for authentication
JEAN2_PORT	8742	Server port
JEAN2_TLS_ENABLED	false	Enable TLS
JEAN2_TLS_CERT_FILE	(unset)	Path to TLS certificate
JEAN2_TLS_KEY_FILE	(unset)	Path to TLS private key