199 lines
4.8 KiB
Markdown
199 lines
4.8 KiB
Markdown
# 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
|
|
```
|