Skip to main content
Version: 0.9.12

Regain superuser access

platform v0.9.11verified 2026-05-14

The Delphi platform always needs at least one superuser — a platform-wide admin who can manage tenants, flags, and onboarding. If you've locked everyone out (departure, MFA loss, accidental demotion), this recipe gets one back.

When to use this​

  • The last known superuser left and their account is gone.
  • MFA was reset on the only superuser and they can't log back in.
  • A migration or admin script accidentally cleared the superuser role.

What you need​

  • SSH access to the Web service host.
  • An email address you control to bind the new superuser to.
  • The expectation that you'll rotate this account again as soon as normal access is restored. Recovery accounts are not for daily use.

Step 1 — Confirm the lockout​

From any logged-out browser, try to log in as a known admin. Note exact errors. If the error is "MFA required" rather than "no such user", the account exists and the Rotate secrets / MFA reset path may be more appropriate.

If you're not sure whether any superuser exists, ask Web operations to check before you re-seed one — see Web operations.

Step 2 — Re-run the superuser registry step​

The setup registry has a keyed step that creates or repoints the platform superuser. Re-run just that step with --force-step:

cd /opt/services/web

docker compose exec -it voiceai-telweb \
  delphi-setup --force-step firstUse.superuser

The step prompts interactively for the email and any required credentials. It is idempotent — re-running won't create a second account if one already exists for that email; it will instead repoint the role.

If you don't have a TTY (CI / automation), run with --non-interactive and the environment variables the step expects. See delphi-setup CLI.

STOP

This step grants platform-wide admin to the email you provide. Confirm the email is one you control and is appropriate for a privileged account before pressing enter.

Step 3 — Verify​

  • The new superuser receives the welcome / verification email (depending on your platform's identity flow).
  • They can log in and reach the platform-admin views — see the Platform admin user guide.
  • The existing tenants are unchanged.

Step 4 — Restore normal admin and revoke the recovery account​

Once normal admins can get back in:

  1. Promote a stable, known admin to superuser via the platform-admin UI.
  2. Demote the recovery account (or delete it) so daily operations don't run with it.
  3. Make a note in your operations log of when the recovery account existed and what changed during that window.

See also​