Howto Recover admin access

How to recover admin access

Use this guide when you are locked out of Bindery's admin account — for example, if the only admin account was deleted, demoted, or you've forgotten the password.

Recovery requires direct write access to the SQLite database file.

---

Option 1 — Reset via the API (if you have any admin session)

If any admin session or API key is still active:

# List users to find the target ID
curl http://bindery:8787/api/v1/auth/users \
  -H "X-Api-Key: <admin-api-key>"

# Promote a user to admin
curl -X PUT http://bindery:8787/api/v1/auth/users/<id>/role \
  -H "X-Api-Key: <admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Option 2 — Direct database update (no admin access required)

No Bindery restart is needed. The change takes effect immediately.

Docker / binary

sqlite3 /config/bindery.db \
  "UPDATE users SET role='admin' WHERE username='<your-username>';"

To promote user ID 1 (the original setup account) by ID instead of username:

sqlite3 /config/bindery.db "UPDATE users SET role='admin' WHERE id=1;"

Kubernetes

# Find the running pod
kubectl get pods -l app=bindery

# Exec in and update the DB
kubectl exec bindery-0 -- \
  sqlite3 /config/bindery.db "UPDATE users SET role='admin' WHERE id=1;"

Refresh your browser — the admin tabs should reappear immediately.

Option 3 — Reset a forgotten password

You cannot hand-craft a password hash. Bindery only accepts argon2id PHC hashes, and there is no shell/CLI tool to mint a valid one outside Bindery (a bcrypt $2y$... hash written to password_hash is silently rejected at login). Use one of the supported paths below instead.

3a — Another admin still exists

Have a working admin reset the locked-out user's password via the API:

# List users to find the target ID
curl http://bindery:8787/api/v1/auth/users \
  -H "X-Api-Key: <admin-api-key>"

# Reset that user's password
curl -X PUT http://bindery:8787/api/v1/auth/users/<id>/reset-password \
  -H "X-Api-Key: <admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"password": "new-password"}'

The user logs in with the new password, then changes it in Settings → My Account → Change password.

3b — No admin exists (locked out entirely)

Delete the user row(s) in the SQLite DB to re-trigger the first-run setup wizard, which lets you set a fresh username + password through the UI:

# Delete a single user by username...
sqlite3 /config/bindery.db "DELETE FROM users WHERE username='<your-username>';"

# ...or, if you're fully locked out, clear the table to force the setup wizard
sqlite3 /config/bindery.db "DELETE FROM users;"

Reload the UI — with zero users, Bindery shows the initial setup wizard. API keys and stored settings are untouched.

Option 4 — Recover an API key

Your API key is stored in the users table. If you need it without logging in:

sqlite3 /config/bindery.db \
  "SELECT api_key FROM users WHERE username='<your-username>';"

Use it as X-Api-Key: <value> in requests.

---

Troubleshooting

Symptom	Cause	Fix
sqlite3: command not found in the Bindery container	distroless image — no shell or tools	Copy the DB out with kubectl cp, edit locally, copy back
Role update applied but UI still shows no admin tabs	Browser cached the old session	Log out and back in, or hard-refresh (Ctrl+Shift+R)
All users have role='user' — how did this happen?	Possible: last admin was demoted via PUT or auto-provisioning reset the role	Apply Option 2 to restore admin, then audit allowed_admin_groups on OIDC providers
sqlite3 reports database is locked	Bindery has the DB open with WAL	The UPDATE is safe to run concurrently — SQLite WAL supports concurrent readers and one writer. If it still blocks, wait a few seconds and retry.

See also: How to add a second user | Troubleshooting | docs/troubleshooting-auth.md