Platform admin, settings, telemetry
Sys-admin routes for tiers, global settings, health, providers, and telemetry.
Intended audience: Stakeholders, Business analysts, Solution architects, Developers, Testers
Learning outcomes by role
Stakeholders
- Clarify platform admin powers versus org admin boundaries.
Business analysts
- Document admin-only workflows for support and operations teams.
Solution architects
- Restrict admin routes via network policy and privileged access tooling.
Developers
- Use cadence:system:* permissions and admin routers safely.
Testers
- Attempt privilege escalation and cross-tenant access negative tests.
Platform admin routes configure the whole deployment: tiers, global settings, telemetry, provider catalog, and health views. Call them only with cadence:system:* permissions. Expect 403 for non–sys-admin tokens. Admin HTTP modules (platform, access, OAuth clients, etc.) live under cadence.api.admin; SettingsService coordinates OrchestratorPool when values affect instances during application lifespan.
Summary for stakeholders
Section titled “Summary for stakeholders”- Blast radius — These routes change behavior for every tenant (tiers, global settings, telemetry, providers).
- Separation of duties — Org admins cannot call platform-admin endpoints; only
cadence:system:*holders can.
Business analysis
Section titled “Business analysis”- Support workflows — Document which ticket types require sys-admin access versus org-scoped admin.
- Audit — Pair admin actions with
cadence:system:*permission names in change records.
Architecture and integration
Section titled “Architecture and integration”- Routers are grouped under
/api/admin/*with fine-grained permission constants; seeregister_api_routersincadence.core.routerfor ordering next to other routers. SettingsServicebridgesglobal_settingsrows and optional RabbitMQ notifications so pool nodes can react without full restarts when messaging is enabled.
Admin surface
Section titled “Admin surface”/api/admin/*— Split across admin routers (tiers, global settings, pool health, provider catalog, access, OAuth clients, etc.).- Permissions —
cadence:system:*strings viaroles_allowed(e.g.SYSTEM_TIERS_READ,SYSTEM_SETTINGS_WRITE,SYSTEM_TELEMETRY_READ).
SettingsService reads/writes global_settings and coordinates OrchestratorPool when values affect instances (see settings_service.pool wiring in application lifespan).
Telemetry
Section titled “Telemetry”/api/admin/telemetry — persists OTel-related keys (otel.*) into global_settings. OrchestratorEventConsumer.reload_telemetry_callback can reload providers when settings.telemetry_changed events fire (when RabbitMQ is enabled).
/api/stats/... — org-scoped usage statistics; permission constants typically ORG_STATS_READ.
Verification and quality
Section titled “Verification and quality”Limitations
Section titled “Limitations”- Strong permissions — Tenant-scoped tokens should not be used for admin routes.
- Telemetry — Changing OTel settings in the database may require a reload path (when messaging is enabled) or a process restart, depending on how the update is applied.
Health checks: public liveness is GET /health (see cadence.api.health.router). Some admin modules add additional health or pool views under /api/admin/... with stricter permissions—open the handler you need before testing.