Skip to content
d3cloud Docs

Admin Settings

Source of truth:

  • d3chat/backend/app/routers/admin.py
  • d3chat/backend/alembic/versions/004_seed_settings.py
  • d3chat/frontend/src/pages/admin/Settings.tsx

Role Requirements

  • GET /api/v1/admin/settings and GET /api/v1/admin/settings/{key}: admin or superadmin
  • PUT /api/v1/admin/settings/{key} and POST /api/v1/admin/settings: superadmin only

Data Shape

Settings are stored as:

  • key: string
  • value: object | null
  • category: string
  • description: string | null

Most built-in settings use:

{ "value": <scalar_or_array> }

Built-in Settings Reference

general

  • app_name (string)
  • app_description (string)

security

  • session_timeout_days (number)
  • max_devices_per_user (number)

registration

  • registration_mode (open | closed | invite_only)
  • registration_domain_allowlist (string array)

branding

  • brand_primary_color (hex color string)
  • brand_accent_color (hex color string)

retention

  • message_retention_days (number)

Note: frontend labels this setting but currently states purge job is not implemented.

Behavior Impact by Setting

Registration controls

registration_mode directly affects POST /api/v1/auth/register:

  • closed -> 403 Registration is currently closed
  • invite_only -> 403 Registration is invite-only
  • open -> registration allowed

registration_domain_allowlist applies if email provided:

  • non-empty list means email domain must be present in allowlist
  • otherwise registration returns 403

Public branding/config

/api/v1/config exposes:

  • app_name
  • app_description
  • registration_mode
  • brand_primary_color
  • brand_accent_color

Example: Update Registration Mode

Terminal window
curl -X PUT "http://localhost:8000/api/v1/admin/settings/registration_mode" \
  -H "Authorization: Bearer <SUPERADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"value": {"value": "closed"}}'

Example: Set Domain Allowlist

Terminal window
curl -X PUT "http://localhost:8000/api/v1/admin/settings/registration_domain_allowlist" \
  -H "Authorization: Bearer <SUPERADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"value": {"value": ["example.com", "company.org"]}}'

Audit Logging

Admin write actions create audit log entries with:

  • admin user id
  • action
  • target type/id
  • details
  • source IP (from x-forwarded-for or client IP)