App·Help

Admin guide

Everything an admin does that doesn't fit in the Settings UI. Read the linked sections as needed; this is the “runbook for the humans” counterpart to the operational runbook (which lives in the repo under docs/runbooks/).

First-day setup

  1. Bootstrap an admin. The very first sign-in needs either a configured VINTEKH_ADMIN_GROUP_IDS Entra group OR the VINTEKH_BOOTSTRAP_ADMIN_EMAIL= escape hatch set to your email. Once you've signed in once, unset the bootstrap env var and configure the group ID via redeploy.
  2. Configure RBAC groups. Decide which Entra groups map to each role and set VINTEKH_ADMIN_GROUP_IDS, VINTEKH_ENGINEER_GROUP_IDS, VINTEKH_VIEWER_GROUP_IDS as comma-separated lists. Confirm at /admin/users.
  3. Connect your first cloud. Go to Sources and connect Azure (Reader Service Principal) or Wiz (device-code). Both are no-admin paths.
  4. Tune MAU. If you're running customer-facing signup, visit /admin/mau-config and set the effective cap. Default 45,000 leaves a 10% margin under the Microsoft 50K free tier.

Day-2 operations

  • Promote / demote a user. /admin/users → select role from the inline dropdown. You cannot demote yourself; ask another admin.
  • Issue an API key for SCIM or programmatic read. Settings → API keys. Pick scope: scim for IdP provisioning, read for SIEM pulls, * for admin scripts. The plaintext is shown ONCE.
  • Audit search. /admin/audit-log. Filter by actor email, tenant, or event kind.
  • Auditor delivery. /admin/soc2-posture — this is your buyer-security-questionnaire one-pager.

Incident response

  1. Acknowledge: post in #incidents Slack and create a status entry.
  2. Visit /status — confirm which dependency is degraded.
  3. Worker outage: check Job table for stuck rows (status="claimed" older than the worker timeout). Reclaim by setting claimedBy=NULL + status="pending".
  4. DB outage: app shell still serves; reads return 500. Use the BYOK key only when the DB is back — we cannot resolve tenants without it.
  5. Post-incident: write a 5-why in docs/postmortems/ and link the AuditEvent rows that capture the relevant actions.

Rotating credentials

  • Source credentials (Azure SP, Wiz token) — rotate at the source, then go to Sources → the source → “Update credentials”.
  • API keys: Settings → API keys → revoke. SCIM clients will start failing within minutes — reissue and re-paste.
  • Bootstrap admin email: unset post-pilot. Long-lived bootstrap is a credential-leak smell.
  • Data key (VINTEKH_DATA_KEY_BASE64) — generate with openssl rand -base64 32 and rotate via redeploy. Old ciphertext under the previous key won't decrypt; the BYOK upgrade lands key-id support that survives rotation.

Off-boarding a user

Best practice: deprovision at your IdP. If SCIM is wired, the user is tombstoned automatically. Manual fallback at /admin/users — we don't delete; we soft-deactivate. Audit trail is preserved.

Browse docs