Howto Add a second user

How to add a second user

Requires Bindery v1.0+ and an admin account. Each user gets their own isolated library — authors, books, downloads, quality profiles, and root folders are scoped per user.

---

Via the UI

1. Log in as an admin.
2. Go to Settings → Users → Add user.
3. Set username, password, and role (user or admin).
4. Click Save.

The new user can log in immediately.

Via the API

curl -X POST http://bindery:8787/api/v1/auth/users \
  -H "X-Api-Key: <admin-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "correct-horse-battery", "role": "user"}'

Response (201 Created):

{"id": 2, "username": "alice", "role": "user"}

Passwords are never returned in responses. The new user's API key is generated automatically and visible to them under Settings → My Account → API Key.

Roles

Role	Can do
user	Manage their own library only
admin	Manage their own library + all admin settings + other users

The first account created in setup is always admin. New accounts via this flow default to user unless you specify "role": "admin".

OIDC / proxy users

For OIDC and proxy-auth modes, users are auto-provisioned on first login — no pre-creation needed. They get the user role by default. To auto-assign admin to specific users, configure allowed_admin_groups on the OIDC provider (see docs/auth-oidc.md).

Promote or demote a user

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

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

List all users

curl http://bindery:8787/api/v1/auth/users \
  -H "X-Api-Key: <admin-api-key>"

Delete a user

Deleting a user does not delete their library data. Reassign or remove their authors and books first:

1. Settings → Users → [user] → Library — view their content.
2. Delete or reassign authors and books.
3. Then delete the user:

curl -X DELETE http://bindery:8787/api/v1/auth/users/2 \
  -H "X-Api-Key: <admin-api-key>"

---

Troubleshooting

Symptom	Cause	Fix
403 Forbidden on user creation	Caller is not admin role	Use an admin account's API key
OIDC user got user role but should be admin	allowed_admin_groups not configured	Add IdP group to provider config; promote the existing account manually with PUT /api/v1/auth/users/{id} + {"role":"admin"}
New user can't see any content	Expected — libraries are scoped per user, starting empty	The new user adds their own authors and root folders

See also: How to recover admin access | Troubleshooting