User Management

User management lives at Admin → Users, and you’ll need the admin role to get in.

Roles

Perch keeps it simple with two roles:

  • Member can view the dashboard, health checks, agents, and containers. No access to admin pages.
  • Admin has full access, including Users, Auth, Instance settings, and the Status Pages admin.

New accounts start as members, whether they’re created by hand or through OAuth. Promote anyone you need to from the Users page.

Creating users

Hit New User and fill in an email and password. The user can change that password from their own Settings page once they’ve signed in.

Tip

If you have OAuth providers enabled, people can skip this entirely and just sign in with their provider. Perch creates the account automatically on first login.

The user detail panel

Click any row in the user list to slide open a detail panel on the right. It shows their email and role, their last login time, and a button to generate a recovery link.

Account recovery

If someone gets locked out (forgot their password, lost access to their OAuth provider), you can generate a recovery link from the detail panel.

The link is single-use and expires after 24 hours. Send it over, and it logs them straight in, where they can set a new password or re-link their OAuth account.

Note

Recovery links don’t show up for admin accounts or your own account. The instance admin is expected to have other ways back in.

Deleting users

Hover a user row to reveal the delete button. Deleting someone removes their account and all their active sessions. There’s no undo, so you’ll get a confirmation prompt first.

The instance admin

The first admin account (seeded from PERCH_ADMIN_EMAIL and PERCH_ADMIN_PASSWORD) is the instance admin. It carries a seeded badge in the user list, and the UI won’t let you delete it, which is there to stop you locking yourself out.

If you ever need to reset the instance admin’s password and genuinely can’t get in, you can update the password_hash column straight in the database:

reset-admin.sh 
docker compose exec db psql -U perch -d perch

Then run an UPDATE users SET password_hash = '...' WHERE email = '[email protected]' with a fresh hash.

Match the hashing Perch uses

Perch hashes passwords with bcrypt at cost 12. Generate your replacement hash the same way (any bcrypt tool at cost 12 will do), or the new password won’t verify.