Authentication

How authentication works in Jean2. Optional token-based auth for your server.

Authentication is off by default. Enable it when you expose your server to a network or the internet.

Enable authentication

Set a single environment variable in ~/.jean2/.env:

JEAN2_AUTH_TOKEN=your-secret-token

Restart the server:

jean2 restart

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

Authenticate 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 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.