Skip to main content
By default, the Datris OSS install runs single-tenant with no login screen — anyone who reaches the UI URL has full access. For shared installs (a team running Datris on a server, a managed deployment, anything past your laptop), turn on user authentication so the UI requires a login and the Configuration tab is admin-only.

​
What it does

When USE_USER_AUTH=true:
  • The UI shows a login screen before any tab is reachable.
  • Sensitive Configuration sub-tabs (Secrets, API-Keys) are gated to admin users. The AI Providers and Environment sub-tabs remain visible to all roles. The Users and API-Keys sub-tabs appear based on the active flags (see the matrix for full visibility rules).
  • A new Users sub-tab appears under Configuration for adding, removing, and changing roles (admin-only by virtue of being inside Configuration).
  • Sessions are server-side, with a TTL index cleaning them up automatically.
When the flag is off, the toggle has zero effect on data — pipelines, taps, secrets, and run history all work the same.

​
Enabling it

  1. Add the flag to your .env: 
    USE_USER_AUTH=true
  2. Recreate the Datris container: 
    docker compose up -d --force-recreate datris
  3. Open the UI. You’ll see the login screen.
  4. Log in as the seed account: 
    Username:  admin
Password:  (leave blank)
    On first login Datris prompts you to set a password (minimum 5 characters). After that, admin is your administrator account.
The default admin row is seeded on every startup (idempotent — only when the user table is empty), regardless of whether USE_USER_AUTH is on. That means flipping the flag on later “just works” — there’s no separate provisioning step.

​
Roles

RoleCan read pipelines / dataCan edit pipelines / taps / secretsCan manage users + Configuration
admin✓✓✓
editor✓✓
viewer✓
All roles see the Configuration tab in the top nav, but the sub-tabs differ: admins see Secrets and API-Keys; editors and viewers see only AI Providers, Users, and Environment. Everything outside Configuration (Pipelines, Taps, Search, etc.) is accessible to all roles per the read/write rules above.

​
Adding users

As an admin: Configuration → Users → Add user. Fill in username + role; the new user has no password until they log in for the first time. Send them their username and tell them to leave the password field blank on first login — they’ll be prompted to set one. You can change a user’s role or delete them from the same screen. Datris won’t let you remove the last admin — there’s an adminCount guard on delete and role-change.

​
Changing your own password

Click your username in the top-right → Change password. Enter your current password and the new one (min 5 chars). If you’ve forgotten your password and there’s another admin: have them delete and re-add your user; the new row will prompt you for a fresh password on next login. If you’re the only admin and you’ve lost the password, you’ll need to clear your user row directly in MongoDB (the user table lives in the platform’s internal database, default oss). After deletion, restart Datris — the seed will recreate admin with a null password and you can set a new one through the UI.

​
Reverting

Set USE_USER_AUTH=false (or remove the line) and recreate the Datris container. The login screen disappears; the Configuration tab is unrestricted again. User rows persist in the database — they just aren’t checked. Flipping back on later returns you to the same set of users with the same passwords.

​
Production checklist

  • Run Datris behind HTTPS before turning auth on. Sessions are cookie-based; without TLS, the login is exposed in transit.
  • Review your CORS allow-list (cors.allowedOrigins in application.yaml) — the default "*" is for local dev only.
  • Pair this with USE_API_KEYS=true for any shared install — user auth gates the UI, API-key gating handles programmatic clients (CLI, MCP, external scripts). API keys are meant to be used alongside user auth: enable the two together. Turning on USE_API_KEYS=true without USE_USER_AUTH=true leaves the browser with no coherent auth mechanism — see supported configurations; the two are designed to compose.
  • API Keys — the paired flag. Required for any deployment where the UI or CLI talks to a real install.
  • Configuring Claude — connecting AI agents via MCP. MCP clients use the API-key path, not user auth.
  • Configuration Reference — the underlying useUserAuth, useApiKeys, and multiTenant keys in application.yaml.