System Admin Access
Summary
System-admin access is for Zeeq operators who need platform-level diagnostics and future operational tools. It is separate from organization roles such as owner, admin, and member.
Configuration
System admins are configured with Platform:SystemAdminSubjects.
Each entry is a provider:subject identity key:
{
"AppSettings": {
"Platform": {
"SystemAdminSubjects": [
"google:108234567890123456789",
"corp-idp:a1b2c3d4-..."
]
}
}
}
For Cloud Run or other environment-variable based deployments, bind the array with indexed names:
AppSettings__Platform__SystemAdminSubjects__0=google:108234567890123456789
AppSettings__Platform__SystemAdminSubjects__1=corp-idp:a1b2c3d4-...
Operators can find their current provider and providerSubject in GET /api/v1/me. Join them with : to produce the configured value.
Security rules
System-admin status is evaluated live on every request from the configured provider:subject allow-list. Adding or removing an entry takes effect on the user's next request; a revoked user does not need to sign out for access to be removed.
Do not configure admin access by email. Email can be unverified, provider-chosen, or reused across providers. Only provider:subject is treated as the stable IdP-verified identity key.
Use trusted providers for deployed environments. Do not add mock: entries outside local development.
The role value system-admin is reserved. Zeeq may attach it to browser cookie claims as a compatibility signal, but admin authorization and /api/v1/me.isSystemAdmin do not trust that claim. Organization roles must never issue system-admin.
Admin API behavior
Admin APIs live under:
/api/v1/admin/**
Unauthenticated and non-admin callers receive 404. This cloaks the admin surface without changing authorization behavior for non-admin routes.
The Vue app uses /api/v1/me.isSystemAdmin to show the System navigation group. Non-admin users who manually browse to /system/diagnostics are redirected to /.
System diagnostics
System admins can open System > Diagnostics.
The page currently has three checks:
| Diagnostic | Purpose |
|---|---|
| Message delivery | Publishes a system message and waits up to 30 seconds for the consumer to write a cache marker. |
| LLM key configuration | Calls the app-level default Fast LLM client with a bounded prompt and timeout. |
| Embedding key configuration | Calls the embedding endpoint to produce an embedding to verify configuration. |
The LLM diagnostic returns generated joke text on success. Treat that value as untrusted model output; the web app renders it as plain text only.
Diagnostics are not rate-limited in this slice. That is an accepted trade-off because the endpoints are system-admin-only.
Existing development-only anonymous diagnostics under /api/v1/diagnostics/** remain separate and are mapped only in Development.