Skip to content

Howto Add a second user

vavallee edited this page Nov 8, 2026 · 3 revisions

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. Open the Users page from the header and click + Add User.
  3. Set username, password, and role (user, requester or admin).
  4. 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", "createdAt": "...", "autoApproveRequests": false}

Passwords are never returned in responses. There is one API key per install, shown to admins under Settings → General → Security; it always acts as an admin, so do not hand it to other users.

Roles

Role Can do
requester Ask for books and authors; an admin approves the requests
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 members of an IdP group, set BINDERY_OIDC_ADMIN_GROUP (see docs/auth-oidc.md).

Promote or demote a user

# Promote to admin
curl -X PUT http://bindery:8787/api/v1/auth/users/2/role \
  -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/role \
  -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

If the user owns library data, Bindery asks what should happen to it: the Users page offers the choice, and the API answers 409 with the row counts until you pick a strategy.

# Hand the library to user 1
curl -X DELETE "http://bindery:8787/api/v1/auth/users/2?strategy=reassign&reassignTo=1" \
  -H "X-Api-Key: <admin-api-key>"

# Or delete the library with the user
curl -X DELETE "http://bindery:8787/api/v1/auth/users/2?strategy=purge" \
  -H "X-Api-Key: <admin-api-key>"

strategy=reassign without reassignTo makes the rows shared with every user. The last admin cannot be deleted.


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 BINDERY_OIDC_ADMIN_GROUP not set Set it to the IdP group, or promote the account with PUT /api/v1/auth/users/{id}/role + {"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

Clone this wiki locally