Skip to content

Authentication Modes

Depictio supports four authentication modes, each designed for a different deployment scenario. Only one mode is active at a time.

Quick Comparison

Auth (default) Single-User Public Demo
Use case Multi-user, enterprise Personal instance Public-facing showcase Guided product tour
Login required Yes No No (browse); Yes (create) No (browse); Yes (create)
Anonymous access None Full admin Read-only Read-only + guided tour
Dashboard creation Registered users Immediate After sign-in After sign-in
User management Full RBAC Disabled Disabled Disabled
Temporary users (24h) No No Yes Yes
Google OAuth Optional Optional Optional Optional
SAML SSO (v1.18.0+) Optional No Optional Optional
Guided tour No No Dashboards list Yes

Auth Mode (Default)

Standard multi-user authentication with full access control.

When to use: Teams and organizations that need user accounts, roles, and project-level permissions.

# Default - no special env vars needed
# Optionally enable Google OAuth:
DEPICTIO_AUTH_GOOGLE_OAUTH_ENABLED=true
DEPICTIO_AUTH_GOOGLE_OAUTH_CLIENT_ID=your-client-id
DEPICTIO_AUTH_GOOGLE_OAUTH_CLIENT_SECRET=your-secret

Google OAuth behind multiple workers

Since v1.5.2 the OAuth CSRF state is shared through MongoDB, so sign-in works with any number of workers or replicas. On earlier versions the state was per-process and the callback only succeeded when it happened to reach the process that issued it. See Security.

Behavior:

  • Users register or are created by admins, unless registration is disabled
  • JWT-based authentication (RS256)
  • Role-based access: admin and regular users
  • Project and dashboard-level permissions (owner, editor, viewer)

Single-User Mode

Zero-friction mode for personal or self-hosted instances.

When to use: You are the only user and want immediate full access without login.

DEPICTIO_AUTH_SINGLE_USER_MODE=true

Behavior:

  • An anonymous user is created with admin privileges
  • No login screen — full access immediately
  • Dashboard creation, project management, and all features available
  • Sidebar shows a "Single User Mode" badge
  • User management UI is hidden (unnecessary with one user)

Public Mode

Read-only anonymous access with optional sign-in for full features.

When to use: Sharing dashboards publicly — visitors can browse without an account, but must sign in to create or edit content.

DEPICTIO_AUTH_PUBLIC_MODE=true

# Backward-compatible alias:
# DEPICTIO_AUTH_UNAUTHENTICATED_MODE=true

Behavior:

  • Every visitor gets a temporary account (24-hour session, cleaned after expiry) with read-only access to public dashboards, without a login screen
  • With Google OAuth or another identity provider enabled, a guest can sign in to a persistent account
  • A short tour of the dashboards list ends by picking a dashboard, where a landing hint points to its Guide (v1.17.4+)
  • After sign-in, users can create dashboards, duplicate existing ones, and manage projects
  • Sidebar shows a "Public Mode" badge

Signing in as a guest (v1.17.3+)

When Google or another identity provider is configured, a guest finds Sign in where they would need it: the avatar menu, the sidebar's mode line (Public mode · Sign in), the profile page, the tour's welcome step and, when viewers may comment, the comments buttons, which open a Sign in to comment prompt. /auth/login shows the sign-in form with Continue as guest, and a sign-in returns to the page it started from. A public instance with password sign-in only behaves as before.

A public showcase where signed-in readers comment combines DEPICTIO_AUTH_PUBLIC_MODE, an identity provider and DEPICTIO_COMMENTS_VIEWERS_CAN_COMMENT. Keep registration open, or a first-time reader's account is never created.

Configuration:

# Temporary user session duration (default: 24h)
DEPICTIO_AUTH_TEMPORARY_USER_EXPIRY_HOURS=24

Demo Mode

Extends Public Mode with a guided interactive tour for first-time visitors.

When to use: Product demos, onboarding, trade shows — guide users through Depictio's features step by step. Can also be repurposed as a self-service tutorial environment.

DEPICTIO_AUTH_PUBLIC_MODE=true
DEPICTIO_AUTH_DEMO_MODE=true

Behavior:

  • All Public Mode features, plus:
  • A 5-step interactive tour appears for new visitors:
    1. Welcome — explains the demo environment and 24h session limit
    2. Explore Dashboards — browse example dashboards
    3. Sign In — create a temporary account or use Google OAuth
    4. Duplicate to Edit — copy an existing dashboard to customize it
    5. Explore Projects — register a project and upload data
  • Tour state is persisted in the browser (won't re-show after completion)
  • Sidebar shows a "Demo Mode" badge

A pipeline often finishes before its owner has an account. Provisioning closes that gap: depictio ingest <results dir> --user alice@example.org creates-or-gets the account, runs as them, and prints a passwordless link to the dashboard it just imported.

Set the shared secret on the instance:

DEPICTIO_AUTH_PROVISIONING_API_KEY=<a long random string>

The provisioning endpoints are disabled while this is unset, so an instance that never sets it cannot have accounts created this way. The CLI must present the same value, through --provisioning-key or the identically-named variable.

Variable Default Description
DEPICTIO_AUTH_PROVISIONING_API_KEY unset Shared secret for POST /depictio/api/v1/auth/provision_user. Unset disables provisioning entirely.
DEPICTIO_AUTH_MAGIC_LINK_EXPIRY_MINUTES see reference How long a magic link stays redeemable.

Treat the key like a password

Anyone holding it can create accounts on the instance. Keep it separate from DEPICTIO_AUTH_INTERNAL_API_KEY_ENV, whose scope is deliberately different. Pass it through a secret store rather than a shell history, and rotate it if a CI log ever captures it.

A magic link is single-use and expires; redeeming it exchanges the ticket for a normal session. Sending it to the user is the pipeline's job; Depictio only emits it on stdout.

Restricting access

Three switches, all opt-in, all independent of the four modes above.

Self-service registration

Set it on an instance where accounts are provisioned by an admin rather than claimed by whoever finds the URL:

DEPICTIO_AUTH_REGISTRATION_DISABLED=true

Behavior:

  • POST /auth/register returns 403, and the Register view and the link to it are hidden
  • Google OAuth, and SAML since v1.18.0, become login-only doors: a known email signs in, an unknown one is refused instead of being provisioned an account
  • Existing accounts, roles and permissions are untouched
  • An administrator can still create accounts with Add user (v1.19.0+)

Password sign-in (v1.8.2+)

Closes email and password sign-in so single sign-on (Google OAuth, or SAML since v1.19.0) is the only way in, for an instance whose accounts all come from one identity provider:

DEPICTIO_AUTH_PASSWORD_LOGIN_DISABLED=true

Behavior:

  • POST /auth/login refuses before reading any credential, so a valid password is not a way around the setting, and the sign-in card hides the form rather than showing one that always fails
  • Ignored unless Google OAuth or, since v1.19.0, SAML is configured, so forgetting the variables gives you the password form back instead of a locked instance
  • Since v1.19.0 it also closes POST /auth/register (403), and the refusal says to use single sign-on
  • DEPICTIO_BOOTSTRAP_ADMIN_PASSWORD is no longer required: OAuth matches the admin by email, so pointing DEPICTIO_BOOTSTRAP_ADMIN_EMAIL at your own Google address is what makes you the admin, with no seeded local account

Public-mode access code (v1.8.2+)

Public mode hands a temporary session to anyone who loads the page. A code makes the instance link-shareable without being world-open:

DEPICTIO_AUTH_PUBLIC_MODE=true
DEPICTIO_AUTH_PUBLIC_ACCESS_CODE=your-shared-code

Behavior:

  • A visitor enters the code before a temporary user is minted, and still gets their own throwaway account: it is a shared secret, not a login
  • Checked in /auth/public/create_temporary_user after the rate limiter, so it is no more brute-forceable than any other credential there
  • Ignored outside public and demo mode

On Kubernetes, all three go under backend.env in your values file.

Choosing a Mode

Personal analytics tool?          → Single-User Mode
Team/org with user accounts?      → Auth Mode (default)
Public dashboard gallery?         → Public Mode
Product demo or guided tutorial?  → Demo Mode