Skip to main content
Version: Next — legacy draft snapshot

Regain superuser access

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.

For routine creation of an additional Super Admin, use Add a Super Admin or Super Viewer. The UI supports this without console access when an existing Super Admin can sign in.

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 Ops service host, directly or through the deployment bastion, with permission to run its Docker Compose setup container. See Instance access and debugging and delphi-setup CLI.
  • Your operator identity and incident/change reference for the recovery audit.
  • 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.

Check with the other designated Super Admins whether any can still sign in. A Team Admin badge in Settings → Users does not establish platform access. A working Super Admin should use the normal role-change workflow instead of recovery.

If none can sign in, contact the operator responsible for the Ops host. From an authorized terminal, connect using your deployment's SSH identity (replace the example values):

ssh -t <operator>@<ops-host>
# For a private Ops host reached through a bastion:
ssh -J <operator>@<bastion-host> -t <operator>@<ops-private-host>

Use one connection method. On the Ops host, confirm /opt/services/ops/delphi-setup.sh is available before continuing; this command is run in the host terminal, not in TelWeb or a database console.

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/ops

./delphi-setup.sh --force-step firstUse.superuser

The step prompts for the account details, password, operator identity, and change reference. It elevates an unambiguous existing usable identity or creates a new credential account when credential sign-in is enabled. It refuses inactive, locked, suspended, or ambiguous/untrusted identities; forcing the step does not bypass those checks. Existing-account elevation preserves memberships and invalidates old sessions. New credential accounts must replace their temporary password at first sign-in. Elevating an existing account with enabled local credentials also resets that credential to the supplied temporary password and requires a password change. An account already marked SUPERUSER is left unchanged by this step; use the documented password-recovery path if that account cannot sign in.

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​

  • Confirm the role notification is delivered; it is queued through Tasker. For a new credential account, deliver the temporary password through your approved channel and complete the required first-login password change.
  • Review SUPER_ADMIN_RECOVERY_ELEVATED in Access logs, including the operator identity and change reference.
  • 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. Sign in as another usable Super Admin and demote the recovery account through the challenged role-change workflow. Then deactivate or delete the Standard User if appropriate. Self-demotion and demotion of the final usable Super Admin are blocked.
  3. Make a note in your operations log of when the recovery account existed and what changed during that window.

See also​