Authentication & Roles

CH-UI has two authentication models depending on how you run it.

Self-Hosted: ClickHouse Credentials

The self-hosted server 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.

Cloud: Magic Link + ClickHouse Credentials

CH-UI Cloud uses a two-layer authentication model:

Console Authentication (Magic Link)

The Console at console.ch-ui.com uses passwordless email authentication:

1. User enters their email address.
2. A magic link is sent to their inbox (via Resend).
3. Clicking the link sets a console_session cookie (30-day expiry).
4. User is redirected to their organization.

No passwords are stored. Rate limits: 10 requests per IP, 3 per email per 15 minutes.

Workspace Authentication (ClickHouse Credentials)

Once inside an org workspace (your-org.ch-ui.com), users authenticate with ClickHouse credentials — identical to self-hosted:

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