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> \
  -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

If you know the username but not the password, update the password hash directly. Generate a bcrypt hash first:

# Using htpasswd (apache2-utils / httpd-tools)
htpasswd -bnBC 12 "" "new-password" | tr -d ':\n'
# Output: $2y$12$...

Then write it to the database:

sqlite3 /config/bindery.db \
  "UPDATE users SET password_hash='\$2y\$12\$...' WHERE username='<your-username>';"

Log in with the new password. Change it to something you'll remember in Settings → My Account → Change password.

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