Skip to content

Upserting a Superuser Credential

Every new instance gets one platform-managed superuser: your account email plus a generated password. When that password is lost, or when the team needs a second login that survives a restore, upsert it — add the account when the email is new, update it when it exists. Other superusers on the instance are never touched.

The managed credential is stored on the platform record, so pbc pocketbase info and the instance detail page keep showing it, and the same email and password work through pbc admin login for everything inside the instance.

Prerequisites

Upsert the credential

Using the portal

  1. Open the instance and go to Settings
  2. Under Admin access, click Set password
  3. Enter the email and a new password, or generate one
  4. Click Save password

The email field starts with the current managed email. The password needs 12–20 characters.

Using the CLI

pbc pocketbase superuser sync --email [email protected] --password 'new-password-here' --name my-app-db
Flag What it does
--email <email> Managed superuser email. Required — new emails are added, existing ones updated.
--password <password> New password, at least 12 characters. Required.
--name <instance> Which instance. Asked for when omitted and no pbc.json binding exists.

Inside a directory with a pbc.json binding, drop the --name:

cd db && pbc pocketbase superuser sync --email [email protected] --password 'new-password-here'

Changed the password in PocketBase admin?

The portal signs in to your instance with the stored credential, so it stops working when the password is changed inside PocketBase admin itself. The overview then shows Admin password changed in PocketBase, and Data, Auth, Logs, settings, email and backups show that the portal cannot sign in. Nothing else on the instance is affected.

Click Set admin password on either message, enter the password you set in PocketBase (or a new one), and save. The portal works again right away. With the CLI, run the superuser sync command above with that password.

What the platform does for you

The sync runs against the live instance and, on success, updates the stored credential in the same step — so the detail page, pbc pocketbase info, and the admin panel agree afterwards. Instances restored from a backup skip the generated password entirely: their superusers come from the backup, and this is how you rotate one of those without knowing the old value.

The password is write-only after saving: the portal shows the email and asks for a new password each time, and the CLI never prints it back.

Next steps