LyDosLyDos
Install
Administrationsuperadmin only

Control Plane Administration

The LYDOS Control Plane exposes a privileged admin API surface for user management, real-time security monitoring, feature flag control, financial operations, and incident tracking.

WARNING
All Control Plane endpoints require the superadmin role claim in the JWT. Regular operator tokens are rejected with 403 Forbidden.

Overview

The Control Plane is the administrative backbone of LYDOS. It aggregates data from all sovereign engines, the user registry, the financial ledger, and the security stack into a unified dashboard API. Every response is hash-chained and audit-logged via ASR.

Route prefix
/api/admin/cp
Auth
Bearer JWT (superadmin)
Audit
ASR hash-chained log
Rate limit
60 req/min per token
Response format
JSON
Min TLS
1.2 (prod)

Authentication & Access

Obtain a superadmin JWT by authenticating via the KSL device-bound login flow. The token must include role: superadmin in its claims. Pass it as a standard Bearer token on every request.

terminalBASH
# Obtain a superadmin token (KSL device flow)
curl -s -X POST http://localhost:8888/api/ksl/auth/device \
  -H "Content-Type: application/json" \
  -d '{"device_id": "<your-device-id>", "role": "superadmin"}' \
  | python3 -m json.tool

# Store the token
ADMIN_TOKEN="<token-from-response>"

# Verify the token resolves to superadmin
curl -s http://localhost:8888/api/admin/cp/dashboard \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool

API Endpoints

All paths are relative to the base URL http://localhost:8888. Every endpoint requires the Authorization: Bearer <token> header.

Control Plane Routes
MethodPathDescription
GET/api/admin/cp/dashboardAggregated system health, active users, revenue summary, and security posture score.
GET/api/admin/cp/usersPaginated user list with role, status, last-seen, and subscription tier.
POST/api/admin/cp/usersCreate a new user with role assignment. Returns new user record.
PUT/api/admin/cp/users/:idUpdate user role, status, or subscription tier.
DELETE/api/admin/cp/users/:idDeactivate a user account. Hard-delete requires additional confirm flag.
GET/api/admin/cp/security/eventsReal-time security event stream — auth failures, anomalies, ASR detections.
GET/api/admin/cp/security/threatsActive threat entries from ASR with severity, evidence hash, and suggested action.
GET/api/admin/cp/finance/summaryRevenue by period, subscription breakdown, ledger balance from FIN engine.
GET/api/admin/cp/system/healthPer-module health scores across all 29 modules and 13 sovereign engines.
GET/api/admin/cp/audit/logsHash-chained audit log — all admin actions with actor, timestamp, and payload hash.
GET/api/admin/cp/flagsList all feature flags with their current values and roll-out percentage.
POST/api/admin/cp/flagsCreate or update a feature flag. Supports boolean, percentage, and allowlist variants.
GET/api/admin/cp/incidentsOpen incidents list with severity, affected components, and resolution timeline.
POST/api/admin/cp/incidentsCreate a new incident. Automatically notifies on-call via the notification engine.
PUT/api/admin/cp/incidents/:idUpdate incident status (open -> investigating -> resolved -> closed).

Dashboard endpoint

The dashboard endpoint is the primary entry point for admin tooling. It returns a single aggregated JSON object covering all major subsystems.

terminalBASH
curl -s http://localhost:8888/api/admin/cp/dashboard \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool

# Example response (abridged):
# {
#   "system_health": { "score": 97, "modules_healthy": 28, "modules_total": 29 },
#   "active_users": 42,
#   "new_users_today": 3,
#   "security": {
#     "posture": "GREEN",
#     "open_threats": 0,
#     "events_last_hour": 14
#   },
#   "finance": {
#     "mrr_usd": 7366,
#     "active_subscriptions": 38,
#     "ledger_balance_usd": 184150
#   },
#   "immunity_mode": "OPERATIONAL",
#   "generated_at": "2026-04-21T10:00:00Z"
# }

User Management

The user management endpoints allow superadmins to create, update, and deactivate users without touching the database directly. All mutations are KSL-signed and recorded in the ASR audit chain.

terminalBASH
# List users (page 1, 20 per page)
curl -s "http://localhost:8888/api/admin/cp/users?page=1&per_page=20" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool

# Create a new operator user
curl -s -X POST http://localhost:8888/api/admin/cp/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "operator",
    "subscription_tier": "pro",
    "send_welcome_email": true
  }' | python3 -m json.tool

# Promote an existing user to admin
curl -s -X PUT http://localhost:8888/api/admin/cp/users/usr_abc123 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}' | python3 -m json.tool

# Deactivate a user
curl -s -X DELETE http://localhost:8888/api/admin/cp/users/usr_abc123 \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool

Security Monitoring

Security events and threat intelligence are surfaced directly from the ASR (Autonomous Security Response) engine. Events are immutable and hash-chained — they cannot be deleted or modified after creation.

terminalBASH
# Recent security events (last 100)
curl -s "http://localhost:8888/api/admin/cp/security/events?limit=100" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool

# Active threats above medium severity
curl -s "http://localhost:8888/api/admin/cp/security/threats?severity=medium" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool

# Example threat entry:
# {
#   "id": "threat_x7k2",
#   "severity": "HIGH",
#   "type": "AUTH_BRUTE_FORCE",
#   "source_ip_prefix": "192.168.1.x",
#   "evidence_hash": "sha256:3f4a...",
#   "detected_at": "2026-04-21T09:45:00Z",
#   "asr_action": "QUARANTINE",
#   "status": "ACTIVE"
# }

Feature Flags

Feature flags allow incremental roll-out of new capabilities without redeployment. Flags support boolean, percentage-based, and user-allowlist variants. Changes take effect immediately across all nodes via GCE state sync.

terminalBASH
# List all feature flags
curl -s http://localhost:8888/api/admin/cp/flags \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool

# Enable a flag for 10% of users
curl -s -X POST http://localhost:8888/api/admin/cp/flags \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new_q300_engine",
    "type": "percentage",
    "value": 10,
    "description": "Gradual roll-out of Q300 engine to 10% of users"
  }' | python3 -m json.tool

# Enable a flag for specific users only
curl -s -X POST http://localhost:8888/api/admin/cp/flags \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "beta_dashboard_v2",
    "type": "allowlist",
    "value": ["usr_abc123", "usr_def456"],
    "description": "Beta dashboard for selected testers"
  }' | python3 -m json.tool

Incident Tracking

The incident tracker provides a lightweight ops workflow for documenting and resolving production issues. Incidents created via the API are automatically correlated with ASR threat events and LSIA immunity mode changes.

terminalBASH
# Create a new incident
curl -s -X POST http://localhost:8888/api/admin/cp/incidents \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Elevated auth failure rate",
    "severity": "HIGH",
    "affected_components": ["auth", "ksl"],
    "description": "Auth failure rate spiked to 12% at 09:30 UTC."
  }' | python3 -m json.tool

# Update incident to resolved
curl -s -X PUT http://localhost:8888/api/admin/cp/incidents/inc_001 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved", "resolution": "Blocked offending IP range via ASR."}' \
  | python3 -m json.tool

# List all open incidents
curl -s "http://localhost:8888/api/admin/cp/incidents?status=open" \
  -H "Authorization: Bearer $ADMIN_TOKEN" | python3 -m json.tool
NOTE
Incidents with severity CRITICAL automatically trigger the LSIA immunity engine to enter DEGRADED mode, which enables additional veto gates on all financial and policy mutations until the incident is marked resolved.

Multi-Region & Governance Panels

Two unified control surfaces aggregate the sovereign engines into the single panes that ship in this release: /control/infra for global multi-region deployment and /control/governance for IPO-grade governance. Both health endpoints (/control/infra/health, /control/governance/health) are public; everything else requires super_admin or auditor role.

terminalBASH
# Public liveness — feeds external load balancers (no auth)
curl -s https://lydos.ailydian.com/control/infra/health | python3 -m json.tool
# → {"status":"healthy","region":"...","node":"...","self":{"available":true,"p95_ms":...,"error_rate_pct":...}}

curl -s https://lydos.ailydian.com/control/governance/health | python3 -m json.tool
# → {"status":"healthy","approval_chain":true,"asr_chain":true}

# Authenticated unified panel
TOKEN="..." # super_admin or auditor JWT
curl -s -H "Authorization: Bearer $TOKEN" \
  https://lydos.ailydian.com/control/infra | python3 -m json.tool
# Returns: self heartbeat, fleet, failover_chain, registry,
#          routing_strategies, immunity_mode, system_risk, asr_posture

# Open a critical-action approval (auto-classifies risk; LSIA veto runs at request time)
curl -s -X POST https://lydos.ailydian.com/control/governance/approvals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "deploy_production",
    "action_payload": {"version": "v12.3.0", "manifest_hash": "..."},
    "requester_id": "ops-eng-1"
  }' | python3 -m json.tool

# Cast a vote (role-diverse quorum; KSL signature mandatory for high/critical)
curl -s -X POST https://lydos.ailydian.com/control/governance/approvals/{id}/vote \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "voter_id": "sec-lead",
    "voter_role": "security",
    "vote": "approve",
    "rationale": "Manifest signed by release key; binary hash matches.",
    "signature": "<KSL device signature>"
  }' | python3 -m json.tool
NOTE
Approval audit chain hashes the insert event only — what was requested, in what order, against which previous insert. Status transitions update status, decision_reason, and decided_at on the same row but never rewrite audit_seq. Tampering with either side surfaces in /control/governance/audit/verify.

Next steps

Sovereign Security Stack
13 engines that power the security layer behind Control Plane
Auth & Organizations
JWT flows, org management, role hierarchy
API Reference
Full REST endpoint catalog
Operator Runbook
Incident playbooks and on-call guides