Users & Accounts

The server requires sign-in before any audiobook data is served. Accounts, sessions, and per-user progress are all handled by the Rust backend.

First-run setup

The first browser to load the app sees a one-time setup form that creates the initial owner account. local setup needs no extra credential and rejects remote setup. lan setup is open to any device on the trusted network — like the sign-in form itself, it relies on the network being private, so complete setup promptly after starting an unclaimed server — the open window never expires on its own, and the server logs a warning at startup for as long as no owner account exists. In proxy mode every setup request must include the random bootstrap token printed in the server console or data/server.log, which remains safe even if forwarded client headers are misconfigured; the token expires after 30 minutes, is consumed after setup, and is never saved to the account store. After that, the home screen is a standard sign-in form. There is no way to skip auth — even the library list is gated.

If the server starts with no accounts at all — a brand-new data directory — it returns to first-run mode.

Storage

Accounts, sessions, progress, per-book settings, and the reading log all live in one SQLite database, data/operalibre.db. Passwords are hashed with Argon2id; session tokens are random opaque strings, and the database stores only a SHA-256 digest of each session and media token, so a copy of the database or of a server backup cannot be used to sign in. Installations upgraded from an older release had their users.json, progress.json, and sibling JSON files imported into the database once, with the originals left in place (and copied to data/backup-pre-sqlite/) as a rollback path — they are never read again after the import.

Sessions are persisted, so restarting the server does not sign anyone out. Each session expires 30 days after sign-in.

Roles

  • Owner — has full administrator access and can promote or demote owners and administrators. Owners always have direct Libation downloads and request-approval permission.
  • Administrator — can add and remove readers, reset reader passwords (except for readers an owner allowed to download from Audible directly), upload books, and run library operations. An owner separately chooses whether each administrator downloads directly or requests each title, and whether they can approve requests.
  • Reader — can browse, stream, and update their own progress and password.

The first account created is always an owner. When upgrading an existing server, the oldest existing administrator becomes the initial owner; existing administrators retain direct-download and approval permissions.

Managing accounts

From the web app, open Administration → Users & access. Owners can:

  • Promote or demote accounts between owner, administrator, and reader
  • Choose direct downloads or approval-required requests for each administrator or reader
  • Grant or revoke request-approval permission for administrators
  • Create, reset, and remove administrator accounts

Administrators can:

  • Add a new reader (username + initial password of at least 12 characters)
  • Remove a reader (their progress is also removed)
  • Reset a reader’s password
  • Choose whether a reader can download Libation titles directly or must request approval for each title

Under Users & access, administrators can also give a reader the full library or a shelf limited to selected books. These restrictions apply to browsing, streaming, companions, downloads, and third-party API access. Approved Audible downloads and imports from a reader’s own Libro.fm account grant that reader access to the resulting book.

Each reader has independent progress, so a household can share one server without stepping on each other’s bookmarks.

Your picture

Open the account menu and select your picture to choose one of the built-in ones, or go back to your initial. It is saved with your account, so it follows you to every device, and administrators see it beside your name under Users & access.

How authentication is wired

The web app exchanges a username + password for a session token and a separate, read-only media token:

  • The session authenticates normal API calls through a cookie or an Authorization: Bearer ... header.
  • The scoped media token is sent as ?token= on audio, cover, companion, download, and OPDS URLs so media elements can load files. It cannot authorize account changes or progress writes. Keep the full session token out of URLs.

Tokens are random opaque strings. Sessions end on logout, account deletion, or 30 days after sign-in.

Failed sign-ins are rate limited: after 5 failures for a username from one address (or 25 from one address across all usernames), further attempts from that address are rejected for 60 seconds. Other devices can still sign in. If a username draws 50 failures from many addresses, each address that has failed against it gets one attempt a minute until the guessing stops; a device that has not failed against it signs in as usual.

The server sees an address, not a device. Devices behind one public address, such as a home router or a mobile carrier, count as one address when they reach the server from outside, and so do all clients of a reverse proxy unless it runs on the same machine and sends X-Forwarded-For. On a public IPv6 network, the 25-failure limit covers the device’s whole /64 network, since a single device can use any address in it. Local IPv6 addresses (link-local, unique local and Tailscale) each count alone, so devices on one network don’t lock each other out; the tradeoff is that a device on your local network that picks its own local addresses isn’t held to that limit.

The server keeps failed sign-ins in a table of limited size. Someone guessing from a very large number of addresses, such as many IPv6 networks or a device on your local network cycling its own addresses, can fill it. New sign-ins are then rejected until the guessing has stopped for a minute. Devices that are already signed in keep working.

Resetting a forgotten admin password

The server owner — the person with shell access to the machine — can recover a lost owner password through the JSON export path:

  1. Stop the server.
  2. From the installation folder, run ./operalibre-server --export-json. This writes the database contents out as JSON files in the data folder and exits.
  3. Move data/operalibre.db (and any operalibre.db-wal/operalibre.db-shm files) out of the way.
  4. Open data/users.json and delete the offending user object — or delete the exported JSON files entirely to return to first-run setup.
  5. Restart the server. It re-imports the edited JSON files into a fresh database.

If you delete just one user, an authorized administrator can create them again with a new password. The server will not allow the final owner to be deleted or demoted. If you removed everything, complete first-run setup again; it follows the same per-mode rules as the first run, including the proxy-mode one-time token.

Avoid hand-editing the password hash. Argon2 hashes include parameters and salts; let the server generate them.