Account recovery & re-running setup

This runbook covers two related situations:

1. You lost the administrator password and need to get back in.
2. 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 human 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 non-system user exists in the user table, setup is considered complete and /setup immediately redirects to /auth/sign-in. Migration-seeded system+…@scrydon.internal service actors are ignored. The wizard created your human administrator account, so the wizard is closed.

So there are two distinct outcomes:

• Keep your data, just get back in → reset the password (recommended).
• Genuinely start over → an operator must remove every human user 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

1. Go to /auth/forgot-password.
2. Enter the administrator's email address.
3. 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:

1. Restore from a recent backup taken while the password was still known — see Backup & restore.
2. 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.
3. Re-run setup (destructive) — only if there is no data worth preserving. See the next section.

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

This re-opens /setup by removing every human user account while retaining the platform's synthetic service actors. Use it only when you intend to start over.

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 human users. Preserve only the canonical migration-seeded actor
--    UUIDs, which retain stable foreign-key identities for audit events.
DELETE FROM "user"
WHERE id NOT IN (
  '00000000-0000-0000-0000-000000000a01',
  '00000000-0000-0000-0000-000000000a02',
  '00000000-0000-0000-0000-000000000a03',
  '00000000-0000-0000-0000-000000000a04',
  '00000000-0000-0000-0000-000000000a05',
  '00000000-0000-0000-0000-000000000a06',
  '00000000-0000-0000-0000-000000000a07',
  '00000000-0000-0000-0000-000000000a08',
  '00000000-0000-0000-0000-000000000a09',
  '00000000-0000-0000-0000-000000000a10'
);

-- 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 when the wizard completes.
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