Authentication & Roles

CH-UI authenticates against ClickHouse credentials over the selected connection tunnel.

Login Flow

1. User picks a connection.
2. User provides ClickHouse username/password.
3. CH-UI verifies credentials through tunnel.
4. CH-UI issues chui_session cookie.

Session Endpoint

curl http://localhost:3488/api/auth/session \
  -H "Cookie: chui_session=..."

Response includes:

• authenticated
• user
• user_role
• active connection info
• app version

Role Resolution

CH-UI supports app-level role overrides for users:

• admin
• analyst
• viewer

Admin-only routes are guarded server-side (RequireAdmin).

Login Failure Statuses

Common statuses returned by /api/auth/login:

• 401 invalid credentials
• 429 IP/user rate limit
• 503 selected connection offline

Logout

curl -X POST http://localhost:3488/api/auth/logout \
  -H "Cookie: chui_session=..."

This deletes the server session and clears cookie state.

Security Notes

• In production, cookie is Secure when app runs in production mode.
• Set strong APP_SECRET_KEY.
• Keep ALLOWED_ORIGINS strict to your UI origin(s).