core/docs/ICD/admin.md

Platform Administration

Cross-cutting admin operations that don't belong to a specific domain.

User Management

GET    /admin/users                  → { "users": [...] }
POST   /admin/users                  ← { "username", "password", "email", "role" }
PUT    /admin/users/:id/role         ← { "role": "admin|user" }
PUT    /admin/users/:id/active       ← { "active": false }
DELETE /admin/users/:id
POST   /admin/users/:id/reset-password  ← { "new_password": "..." }
POST   /admin/users/:id/vault/reset     → destroys user's UEK (BYOK keys lost)

Global Settings & Policies

Settings are key-value pairs in global_settings. Policies are boolean flags that gate features.

GET /admin/settings                  → all settings
GET /admin/settings/:key             → single setting
PUT /admin/settings/:key             ← { "value": ... }

The handler auto-detects: if the value is a string and the key is a known policy name, it writes to the policies table. Otherwise it writes to global_config as JSON.

Public settings (non-admin, for FE bootstrapping):

GET /settings/public

{
  "banner": { "enabled": true, "text": "DEVELOPMENT", "bg": "#007a33", "fg": "#ffffff", "position": "both" },
  "branding": { "instance_name": "Switchboard", "logo_url": "...", "tagline": "..." },
  "has_admin_prompt": true,
  "storage_configured": true,
  "paste_to_file_chars": 2000,
  "policies": {
    "allow_registration": "true",
    "allow_user_byok": "true",
    "allow_user_personas": "true"
  }
}

Banner Configuration

The environment banner is stored as a single global_config entry under the key "banner". It's a simple object:

{
  "enabled": true,
  "text": "DEVELOPMENT",
  "position": "both|top|bottom",
  "bg": "#007a33",
  "fg": "#ffffff"
}

Set via PUT /admin/settings/banner with { "value": { ... } }. The admin UI provides a color picker, position selector, and preset dropdown. The Go template base layout reads the banner from PageData and renders top/bottom strips with CSS custom properties.

Platform Stats

GET /admin/stats

{
  "users": 42,
  "channels": 156,
  "messages": 12847
}

Storage & Vault

Storage status:

GET /admin/storage/status            → { "backend", "healthy", "file_count", "total_bytes", ... }
GET /admin/storage/orphans           → { "count": 3 }
POST /admin/storage/cleanup          → removes orphaned blobs
GET /admin/storage/extraction        → extraction queue status

Vault:

GET /admin/vault/status              → { "encryption_key_set", "user_vaults_count", ... }

Audit Log

GET /admin/audit?page=1&per_page=50&action=user.create&actor_id=uuid
GET /admin/audit/actions             → { "actions": ["user.create", "policy.update", ...] }

Audit entry:

{
  "id": "uuid",
  "actor_id": "uuid",
  "action": "user.create",
  "resource_type": "user",
  "resource_id": "uuid",
  "metadata": {},
  "created_at": "..."
}

Usage & Pricing

GET /admin/usage                     → { "totals", "results" }
GET /admin/usage/teams/:id           → team-specific usage
GET /admin/usage/users/:id           → user-specific usage
GET /admin/pricing                   → { "data": [...] }
PUT /admin/pricing                   ← { "provider", "model", "input_per_m", "output_per_m" }
DELETE /admin/pricing/:provider/:model

Personal usage (non-admin):

GET /usage                           → { "totals", "results" }

Scoped to the user's BYOK provider usage only.

Roles (Platform)

GET    /admin/roles                  → { "roles": [...] }
GET    /admin/roles/:role
PUT    /admin/roles/:role            ← { "permissions": {...} }
POST   /admin/roles/:role/test       ← test role permissions

Email Test

POST /admin/notifications/test-email

{ "to": "admin@example.com" }

Sends a test email using the configured SMTP settings.

---

Archived Channels

GET    /admin/channels/archived      → { "data": [...] }
DELETE /admin/channels/:id/purge     → permanent delete (ignores retention)

Auth: Platform admin.

Surfaces Admin

See surfaces.md for the full surface management API.

GET    /admin/surfaces               → all surfaces (including disabled)
GET    /admin/surfaces/:id           → surface with manifest
POST   /admin/surfaces/install       ← multipart .surface archive
PUT    /admin/surfaces/:id/enable
PUT    /admin/surfaces/:id/disable
DELETE /admin/surfaces/:id

Tasks Admin

See tasks.md for the full task management API.

GET    /admin/tasks                  → all tasks across all users/teams
POST   /admin/tasks/:id/run          → force run
POST   /admin/tasks/:id/kill         → cancel active run
DELETE /admin/tasks/:id              → delete task