# 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
```

```json
{
  "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:

```json
{
  "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
```

```json
{
  "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:

```json
{
  "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
```

```json
{ "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](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](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
```