Account recovery & re-running setup

Regain admin access after a lost password, and the operator procedure to re-open the first-run setup wizard.

This runbook covers two related situations:

You lost the administrator password and need to get back in.
You want to re-run the first-run setup wizard (/setup) — for example, to start the platform over from scratch.

Read the next section first: it explains why /setup does not simply re-open, so you choose the right recovery path.

Why `/setup` won't re-open on its own

The setup wizard is gated on whether any user account exists — not on a "setup is done" toggle you can flip back.

When the browser loads /setup, the platform asks the auth service for setup status. That status is computed from the auth database: if at least one row exists in the user table, setup is considered complete and /setup immediately redirects to /auth/sign-in. The wizard created your administrator account, so a user exists, so the wizard is closed.

There is a setup_completed flag stored in the platform_config table, but it does not control whether the wizard re-opens. It exists only to protect the one-time "promote the person who finishes setup to super-admin" step from being replayed. The gate the UI actually checks is "does any user exist?". Auto-healing the wizard off the user table means an environment that lost the flag (e.g. after a migration) can never get re-stuck in the wizard.

So there are two distinct outcomes:

Keep your data, just get back in → reset the password (recommended).
Genuinely start over → an operator must empty the user table so the wizard re-opens. This is destructive — see the warning below.

Recommended: reset the password (keeps everything)

This is almost always what you want. Nothing is deleted; the locked-out admin simply gets a new password.

If email delivery is configured

Go to /auth/forgot-password.
Enter the administrator's email address.
Follow the reset link delivered to that mailbox.

A passwordless magic link at /auth/magic-link works the same way — enter the email, click the link, then set a new password under Settings → Account.

Both paths require working email delivery (the SMTP / Resend / SendGrid provider you configured during setup). If the colleague who knows the password is on holiday but can still receive mail, they can complete this themselves from anywhere.

If email delivery was skipped during setup

The Email step in the wizard is optional, so a deployment can reach this state with no way to send a reset link. In that case, an operator with cluster access has to step in. In order of preference:

Restore from a recent backup taken while the password was still known — see Backup & restore.
Set the password through the running api-platform service. Passwords are stored in the account table as a salted hash produced by Better Auth's own hasher, so you cannot paste a plaintext password in with psql — it has to be hashed the same way. Use the auth service's admin password-set path rather than editing the column directly. Contact Scrydon support if you need help wiring this up.
Re-run setup (destructive) — only if there is no data worth preserving. See the next section.

Do not try to "fix" email by inserting SMTP credentials directly into platform_config with SQL. The smtp_password and email_api_key values are meant to be encrypted at rest by the secrets layer. A hand-inserted plaintext row is stored unencrypted — the default local provider reads it back via plaintext passthrough so it may appear to work, but behaviour varies by secret provider (BYOK/HYOK may reject or mishandle it), and you've left a credential sitting in the clear. Reconfigure email through the wizard or Settings → Email so the values are encrypted correctly.

Last resort: re-run the setup wizard (destructive)

This re-opens /setup by removing every user account. Use it only when you intend to start over.

This deletes all user accounts and everything keyed to them. Deleting the user table cascades broadly across the auth schema — credential and OAuth accounts, sessions, passkeys, organization and team memberships, pending invitations, org-chart assignments, clearances, and any personal workspaces owned by a user (workspace.owner_user_id). It can also orphan data in the other databases (agentic, analytics, ontology) that references now-deleted workspace or environment IDs. Your shared organizations themselves survive (they have no foreign key to user) but become inaccessible — re-running the wizard creates a brand-new organization, and the old one has no members attached to it. Take a backup first.

An operator with database access runs this against the auth database. For the bundled in-cluster Postgres:

kubectl exec -it deploy/db -n scrydon-platform -- \
  psql -U postgres -d auth

For a managed Postgres instance, connect to the auth database with your usual client. Then:

-- 1. Remove all users. Cascades widely (accounts, sessions, memberships,
--    personal workspaces, ...). This is what re-opens /setup — the gate is
--    "does any user exist?".
DELETE FROM "user";

-- 2. Clear the setup-completion flag. Recommended hygiene: it resets the
--    completion / replay-protection state to a fresh-install baseline. The
--    new admin is promoted to super-admin either way — the first user created
--    in an empty user table is auto-promoted by the signup bootstrap hook.
DELETE FROM platform_config WHERE key = 'setup_completed';

Then visit /setup and complete the wizard again.

Notes:

Your license survives. It lives in platform_config (license_jwt), which is untouched, so the wizard's License step shows as pre-validated.
Email config survives in platform_config but is now attached to the old (orphaned) organization for org-scoped values; re-confirm it in the new org via Settings → Email.
If you want to keep the existing organization and its data, do not use this procedure — recover the password instead (see above), or contact Scrydon support to re-attach a recovered admin to the existing organization.

Quick reference

Situation	Action
Lost password, email works	Self-service `/auth/forgot-password` or `/auth/magic-link`
Lost password, email skipped	Restore from backup, or operator sets password via `api-platform`
Want to start completely over	Operator: `DELETE FROM "user"` + clear `setup_completed`, then `/setup`
Want to keep org data	Never delete users — recover the password instead