Web app and sign-in reference
This page is the reference for the web app's roles, sign-in methods, routes and screens. For a plain-language tour, see The web app.
The web app is a React single-page app (SPA) that bookclerkd serves. It
covers Discover, Wishlist, the library and account linking. It talks only
to Bookclerk's Rust HTTP API; TypeScript never hosts the API.
| Role | Signs in with | Can do |
|---|---|---|
| Operator | The operator token, until an Owner exists; then a sign-in link or Owner elevation | Everything on the server, except connect stores |
| Owner | Invite link, password, passkey, SSO or integration login | Administrator powers, plus elevation to operator and Settings → Nodes for the nodes they own |
| Administrator | Invite link, password, passkey, SSO or integration login | Member powers, plus acquire and scan for every store account, jobs, adding users and Settings → Nodes for the nodes they own |
| Member | Invite link, password, passkey, SSO or integration return visit | Discover, Wishlist, browsing the shared library, Accounts, scan and acquire for the store accounts linked to them (through the API), and their own Settings → Account; a Member who owns a node (a branch they linked) also gets Status and Settings → Nodes for the nodes they own |
The operator runs the server. They get the full library, scan, acquire, jobs, Discover, Wishlist, Settings (daemon, plugins, confinement) and impersonation. They cannot connect stores, because stores belong to people.
How the operator signs in:
- Before an Owner exists, paste the operator token from
bookclerk daemon token. - After that, the web app refuses the pasted token
(
POST /api/auth/loginreturns 403). Use the tray's Copy sign-in link, runbookclerk login, or sign in as an Owner and elevate.
The Bearer API keeps accepting the token. The sign-in link is a loopback
GET /api/auth/tray-handoff?code= URL with a one-time code (180 seconds by
default), never the durable token.
The desktop window follows the same rule: it is the operator only until an Owner exists, then the patron whose session the branch keeps for it, who elevates like anyone else (see the desktop window).
An Owner can elevate to operator, with an IdP step-up, a passkey or their password. Elevated, they get Server and Plugins settings and impersonation. Administrators can add users but cannot elevate.
Some changes need elevation because each one decides who can sign in, or deletes something hard to rebuild. An Owner's everyday session can read these but not change them:
- the second-factor policy (
PUT /api/auth/mfa-policy); - upstream sign-in providers and the public origin
(
PUT /api/auth/oidc/config); - Bookclerk-as-identity-provider clients (create, update, rotate the secret, delete);
- removing a shared branch (
DELETE /api/config/nodes/{node_id}).
Because the second-factor policy and the sign-in providers need elevation, an Owner who can't elevate also can't weaken the checks that guard elevation.
Wrong elevation passwords count toward the same lockout as other sign-in
attempts, both for the client address and for the Owner. After too many
misses, POST /api/auth/elevate answers 429 with a Retry-After header,
even from another address, until the lockout ends. A passkey or IdP step-up
still works meanwhile.
The Owner's count is the account's password lockout, which every password
re-check by a signed-in user shares: elevation, changing your password, and
the current_password that changes to your own sign-in ask for once a
session is more than fifteen minutes old (authenticator and passkey
changes). Misses on any of them add up, and while the account
is locked each answers 429. A correct password clears the count.
TOTP (an authenticator app) is a second factor for password sign-in.
- When TOTP is on, a password sign-in returns
{ mfa: { method: "totp", challenge_id } }instead of a session cookie. - Passkey sign-in never asks for a TOTP code.
- Enrolling shows a QR code, a setup key to copy, and an
otpauth://Open in authenticator app link.
Requiring a second factor. Set require_second_factor in
Settings → Sign-in, in [daemon.auth], or with
BOOKCLERK_DAEMON_AUTH_REQUIRE_SECOND_FACTOR. Then:
- A password sign-in needs a TOTP code, or the user signs in with a passkey.
- A user with neither still gets a session, so they can enroll. The web app shows a blocking dialog: set up a passkey or authenticator, or log out and finish later.
- Logging out doesn't lock the account.
A failed password sign-in returns
{ error: "invalid_credentials", message: "Invalid login or password." }.
- Passkeys can have a name of up to 80 characters. An empty name shows as
Passkey. - The relying party is
integrations.public_origin. Without one, it is the loopback origin the request came in on, and otherwisehttp://localhost:8787. - Loopback IP addresses are rewritten to
localhost, because a WebAuthn relying party can't be127.0.0.1. - The web app gives up on a passkey prompt after 45 seconds, and skips
passkeys in browsers without
PublicKeyCredential, so people can fall back to a password.
Important
Open the web app at http://localhost:… (the tray does), not at the
raw IP address. On a production server, set
integrations.public_origin.
People can sign in with Google, GitHub, Apple, Discord or a custom OpenID
Connect provider (configured in [auth.oidc] or Settings → Sign-in).
Bookclerk is the client.
- The social presets ask only for a client ID and secret, and turn on Link by verified email by default. Advanced adds group mapping.
- A custom provider gets the full OpenID form, with linking by email off.
Bookclerk can also be the identity provider for other apps, such as Audiobookshelf.
- Each client card has an on/off switch, redirect URIs, public (PKCE) or
confidential (the secret is shown once), refresh tokens, and the
openid,profileandemailscopes. - Client secrets are sealed in
encrypted_secretsand never shown again. - An installed player plugin, such as Audiobookshelf, adds a read-only client whose callbacks come from that plugin's server address. Custom clients stay fully editable.
- With an empty
public_origin, Bookclerk uses the loopback origin (localhostunder the tray orcargo dev). Saving an empty origin clears a pin, so loopback detection keeps working.
Note
Port 13378 is Audiobookshelf's own web UI. Bookclerk listens on
8787 by default (daemon.listen).
GET /api/auth/signin (public) returns
{ operator_token, oidc, integrations }. The screen shows username and
password first, then SSO and integration logins as buttons. The
operator-token box appears only while operator_token is true, that is,
while no Owner is active.
The SSO buttons use each brand's own mark, colors and wording (Continue with {Brand}), and follow the app's resolved theme rather than the OS hint alone:
| Brand | Light theme | Dark theme |
|---|---|---|
2025 gradient Super G on white #FFFFFF, #747775 stroke, #1F1F1F Google Sans Medium |
#131314 fill, #8E918F stroke, #E3E3E3 label; the G stays on a white tile |
|
| Apple | Black button | White button, black logo and title |
| GitHub | Invertocat on #1F2328 |
Black Invertocat on white |
| Discord | Clyde on Blurple #5865F2 |
White Clyde on black |
| Item | Detail |
|---|---|
| Operator token | Sealed in encrypted_secrets, or set by BOOKCLERK_OPERATOR_TOKEN. bookclerk daemon token prints it |
| Sign-in link | Tray Copy sign-in link or bookclerk login: a loopback ?code= URL, valid 180 seconds by default; the tray then removes that URL if it is still on the clipboard |
| Operator cookie | bookclerk_operator_session (Path=/), also used by elevated Owners |
| Portal cookie | bookclerk_portal_session (Path=/), the session of a first-party user |
| Library card | A clerk's session, sent as Authorization: Bookclerk-Clerk <token>, never as a cookie (see Library cards) |
| Player card | A player app's sign-in at /player, sent as Authorization: Bearer <token> or ?token=, made from a player password or a browser approval, never the account password (see Player apps) |
| Config | [daemon.auth] |
| Preferences | Stored in the database (user_preferences), not config.toml |
A clerk can show a person's books from a library without joining it as a branch. It signs in as the person and holds a library card: a session token in the person's session list, not a node.
Note
A clerk is another Bookclerk install that a person uses to reach a
library. The API and the code use the same word: the built-in OAuth
client bookclerk-clerk, the Authorization: Bookclerk-Clerk scheme,
the /api/clerk/ routes and the clerk session kind. Only OAuth's own
parameter names, such as client_id, keep their standard spelling.
- The clerk sends the browser to the library's
/oidc/authorizewith the built-in public clientbookclerk-clerk, the scopelibrary:member, an S256 code challenge, astate, a loopback orhttps://redirect URI, and aclerk_name. - The library sends the request to
/clerk/approve, which signs the person in and asks "Give name a library card for library?", where name is the name the clerk gave itself. Approving needs an active user and the node API transport policy (TLS, except on loopback). It does not need "Let new branches join". - The library sends the browser back with a single-use code that lives 60 seconds.
- The clerk redeems the code with its verifier at
POST /api/clerk/v1/tokenand gets{ token, library_id, user, idle_secs }. The token is shown once; the library keeps only its hash. Any failed redeem spends the code.
The clerk then sends Authorization: Bookclerk-Clerk <token>:
- It works only on the routes any library session may use: the library, Discover, the wishlist, the request queue, preferences, the person's profile and sessions, and sign-out. Every other route, administration included, sees no credential and refuses it, whatever the person's role.
- It needs TLS, except on loopback, like the node API. Otherwise the
route answers
403 transport_insecure, or403 clerk_sign_in_unavailablewhere this daemon doesn't serve remote installs. - It is never a cookie, and a browser's session token is never a library card.
- Each use keeps it signed in for another 90 days. Sign-out
(
POST /api/auth/logout) ends it, and so does Revoke in the person's sessions or disabling the user. When the library can't end the card's session, sign-out answers 503sign_out_failedand the card stays signed in. - It belongs to the sign-in that approved it, so it is listed and revoked beside that browser session, including a sign-in through an integration such as Audiobookshelf.
bookclerk-clerk codes are never redeemed at /oidc/token, and
bookclerk-clerk can't be registered as a client.
With its library card, a clerk keeps one WebSocket open to the library at
GET /api/clerk/v1/connect, so it hears about changes instead of polling.
It shows the library's books to the person, and is not a branch link: the
library never sends work on it.
- The clerk connects with
Authorization: Bookclerk-Clerk <token>and the subprotocolbookclerk-clerk.v1, over TLS except on loopback. - The library answers
hellowith the topics the card hears about (libraryanddiscover), thenchangedwhenever one of them moves. - The clerk asks for the library's books a page at a time with
{"v":1,"type":"books","after":""}. The library answersbooks.pagewith up to 100 works, each with its identifiers and the library's editions of it, and the cursor for the next page (none on the last page). The pages list every book on the library's store accounts, as its own Library page lists them for a member. Each edition is{"edition": {...}, "yours": true}when it is on a store account linked to the card's person;yoursis left out otherwise. An edition whose audio the library already holds also carriescopy:content_type(a media type such asaudio/mp4),bitrate_kbpsandsource_store(the store the file came from) when the library has probed the file,losslesswhen true, andversion, a short opaque string that changes when the library's file does.copyis left out for an edition the library has not downloaded. After those, the pages go on with the books only the library's branches hold: editions a branch it trusts listed in the last two days (the ones Discover and search show as available through a branch) that no store account of the library holds. Each such edition has"availability": "reachable", no formats, nocopyand neveryours, and the page doesn't say which branch lists it. A branch reading the library's books never gets these. A cursor is an opaque string of up to 64 letters, digits and-. The clerk sends it back unchanged as the nextafter. A frame it cannot read getserrorwith codeinvalid. - The clerk asks for the library's copy of an edition with
{"v":1,"type":"copy.grant","store":"…","marketplace":"…","product_id":"…"}, naming the edition by a store listing from a page (marketplaceis left out for a store without marketplaces). The library answerscopy.grantedwith the same listing, acopy_id, atoken,expires_in_secs(one hour),copy(as on a page) andfiles: each file'sname,roleandsize, the primary audio first. The clerk downloads filenof that list withGET /api/copies/v1/{copy_id}/files/{n}andAuthorization: Bookclerk-Copy <token>; oneRangeis honoured, so a broken download resumes. An edition the person may not take, or one the library holds no copy of, getserrorwith codenot_found; the two are not told apart.unavailablemeans try again later.
Answers come in the order the frames were asked.
A clerk asks for a copy when one of its own acquires wants that edition, and takes it when the library downloaded it from the same store, or when it is better than the clerk's own download from another store (see When a branch takes the copy, which a clerk follows too). The clerk keeps the token only while the acquire runs and keeps it out of its own logs.
The copy token is good only while the card is: the library checks on every download that the card is still signed in and its user is not disabled, that the person may still see the edition and that the files are the ones it listed. Once the card is signed out, every new download request is refused; a file already being sent is not cut off. See Taking a copy from the library for the download route's answers.
Note
The token is frame text on this socket, where a branch's is sealed to its key: a clerk has no key of its own, and the socket is the card's own connection, which is TLS except on loopback. Treat it like the card. The library stores only its hash and keeps it out of its logs.
The library checks the card again every 30 seconds, and before every page
and every copy it grants,
and closes the socket with code 4401 once the card is signed out, revoked,
expired, its user disabled, or its person must enroll a second factor (a
new socket then gets 403 mfa_enrollment_required). A socket the clerk
leaves silent for 60 seconds is closed, as is one that has not taken a
frame within 10 seconds, and a library serves at most 512 clerk sockets at
once (more get 503 clerk_sockets_busy).
On the clerk, the operator or an Owner signs this install in to a library. The daemon, never the browser, talks to the library:
POST /api/config/clerk/inspect{ address }reads the library'sGET /api/node/v1/infounder the node API transport policy. A self-signed library's fingerprint comes back to confirm.POST /api/config/clerk/start{ address, fingerprint?, clerk_name? }reads the library again, checks the confirmed fingerprint, and answers the authorize URL to open. The name defaults to this machine's name. The verifier andstatestay in the daemon's memory for 10 minutes; a restart forgets them. The redirect comes back to this install's/clerk/callback.POST /api/config/clerk/callback{ code, state }redeems the code with the verifier, checks the answer is for the library that was inspected, and seals the card into the database (encrypted_secrets, kindclerk_card). A sign-in is used once, whatever the outcome.
Then the daemon keeps the library's clerk socket open with the card:
- It reads every page of the library's books on each connection, whenever
the library sends
changedforlibrary, and every 30 minutes. Once the last page is in, it drops the books the read no longer named. A read cut short drops nothing. - The books show in Books in other libraries
(
GET /api/config/join/window, which lists the libraries incards), merged with the books of any library this install is a branch of. Each edition there carriesyours, and the person's own are marked Yours. An edition the library has no copy of also carriesrequest: the library's own work id (work_id) and where a copy would come from (from):librarywhen one of the library's own store accounts holds it,branchwhen only one of its branches lists it. - A lost connection is dialed again after 5 seconds, doubling up to 5 minutes.
- When the library ends the card (close 4401, or 401 on connecting), the
card and its books are dropped here, and the library stays listed as
signed_outso the person can sign in again.
POST /api/config/clerk/request { library_id, work_id, from, node_id? }
asks the library for a copy of a book it has none of, with work_id and
from taken from the edition's request. The daemon sends one of the
library's own member routes with the card, as the person's browser
session there would:
frombranch:POST /api/branch-requests. The library decides whether a branch it trusts lists the work and which branch it asks.fromlibrary:POST /api/download-requests. The library downloads the book on the store account that holds it (see Asking the library to download a book).node_idis refused here.
Either way the person's member controls there decide whether they may ask (Request books). The daemon reads only the status of the library's answer:
| Answer | Means |
|---|---|
200 { library_id } |
The library took the request. A branch request shows there with the person's other requests; a download shows in its jobs. |
400 invalid_request |
The work or node id is malformed, or a node id came with from library. |
403 not_allowed |
The library's member controls turn requesting books off for the person. |
404 not_found |
This install holds no active card for that library. |
404 not_listed |
No branch of the library lists the work now (branch), or none of its store accounts holds it (library). |
409 already_there |
The library already has a copy (library); it shows after the next read of its books. |
502 card_refused |
The library no longer accepts the card; sign in again. |
502 unreachable or library_error |
The library couldn't be reached in 15 seconds, or answered with another error. |
503 library_busy |
The library's job queue is full. |
GET /api/config/clerk lists the cards. POST /api/config/clerk/sign-out
{ library_id } ends the card at the library (POST /api/auth/logout
with the card) when it can be reached, then drops the card, its books
and the library from the list. The answer's library_signed_out says
whether the library ended its session too; when it is false, the
person can revoke the session from their session list there.
An install that is already an active branch of a library reads
that library's books through its link, so a card for it is refused
(409 already_joined). These routes are for the operator or an Owner.
A card can replace a branch instead. POST /api/config/clerk/start
{ from_branch, clerk_name? } (a library id instead of address and
fingerprint) signs in to a library this install is an active branch of,
with the address and pinned certificate of the branch link. Only the
operator may, as only the operator leaves a library (403 otherwise), and
the library must still answer with the same library id (409
origin_mismatch) and certificate (409 fingerprint_unconfirmed). The
callback gets the card from the library first, then leaves the branch as
POST /api/config/join/leave does, then seals the card. Both run on their
own task, so a request cut short still finishes them. The answer's
left_branch.owner_notified says whether the library was told. If the
person doesn't approve the card, the branch stays. The sign-in remembers
which enrollment it replaces: if this install left and joined the library
again before the callback, the callback answers 409 enrollment_changed
and keeps the new branch.
The other way, a branch join of a library this install holds a card for signs the card out (see How the sign-in works).
In the web app this is Settings → Library → Library cards: Sign in
with a library card reads the library, asks for the fingerprint and the
name, and sends the browser to the library's sign-in page. The library
sends it back to /clerk/callback, which posts the code and state to
POST /api/config/clerk/callback and removes them from the address bar.
Only a request that got no answer offers Try again; any answer ends
the pending sign-in. In Books in other libraries, a book a library
has no copy of has a Request button; one only the library's branches
hold also says "On a branch of" that library. Each card in the list has Sign out (Remove once
the library ended it), and for the operator Make this server a branch.
A branch in Settings → Library has Use a library card instead. See
Sign in with a library card.
| Area | Endpoints |
|---|---|
| Who am I | GET /api/auth/me |
| First Owner | POST /api/auth/bootstrap (operator, once, while no Owner exists) |
| Users | GET/POST /api/users, PATCH /api/users/{id}, POST /api/users/{id}/claim-ticket (operator, Owner or Administrator) |
| Profile | PATCH /api/auth/profile { display_name?, email?, avatar_source? }; PUT/DELETE /api/auth/profile/avatar; GET /api/users/{id}/avatar (any signed-in user) |
| Elevation | POST /api/auth/elevate { password }, DELETE /api/auth/elevate, GET /api/auth/oidc/elevate, POST /api/auth/passkeys/elevate/* (Owner only) |
| SSO | GET /api/auth/oidc/providers, /login, GET/POST /callback |
| SSO settings | GET/PUT /api/auth/oidc/config (providers, public_origin, detected_origin, issuer URLs; Owner or operator reads, operator changes) |
| Bookclerk as IdP | GET/POST /api/auth/oidc/clients, PUT/DELETE /api/auth/oidc/clients/{client_id}, POST /api/auth/oidc/clients/{client_id}/rotate-secret (Owner or operator lists, operator changes) |
| Passkeys | GET/POST/DELETE /api/auth/passkeys… (sign-in, register, elevate) |
| TOTP | POST /api/auth/totp/enroll/begin and /finish, GET/DELETE /api/auth/totp, POST /api/auth/totp/login |
| Second-factor policy | GET/PUT /api/auth/mfa-policy { require_second_factor } (Owner or operator reads, operator changes) |
| Preferences | GET/PATCH /api/preferences: default_view, disabled_shelves, theme (subject user:{id}, portal:{identity_id} or operator) |
| Portal | /api/portal/* (Accounts, invite claims) |
| Library cards | GET/POST /api/auth/clerk-consent (the consent page, any signed-in user), POST /api/clerk/v1/token (the clerk redeems its code), GET /api/clerk/v1/connect (the clerk socket) |
| Library cards (clerk side) | GET /api/config/clerk, POST /api/config/clerk/inspect, /start, /callback, /sign-out (operator or Owner) |
GET /api/auth/me returns
{ authenticated, role, default_view, can_acquire, elevated, administers_nodes, impersonating?, portal?, user?, second_factor? }:
roleisoperator,owner,administratorormember.administers_nodesis true for the operator, an Owner or Administrator, and a Member who owns a node. The web app shows Status, and the nodes in Settings, only when it is true.useris the first-party user, when there is one.default_viewcomes from the caller's preferences.- Portal users also get
second_factor: { required, totp, passkey_count, enrolled }.
When the library does not answer in time to check a portal session (a
busy or still-starting server), /api/auth/me and the signed-in API routes
answer 503 with Retry-After and the slug session_check_unavailable,
not 401. The request is still refused, but the web app waits and asks
again instead of showing the sign-in screen. The routes that check the
session themselves (elevation, passwords, users, sessions, passkeys, the
authenticator app, the profile and linked sign-in identities) answer the
same way.
Note
A request that carries the operator token still goes ahead when it also carries a portal cookie that cannot be checked: deleting a user and setting a user's password do not wait on the portal session.
The web app keeps the address bar in step with the screen:
| Path | Screen |
|---|---|
/ |
The user's default_view; the address then changes to that path |
/discover |
Discover |
/library |
Library |
/wishlist |
Wishlist |
/accounts |
Accounts |
/settings |
Settings |
/invite |
Claim an invite (?ticket=) |
/clerk/approve |
Give a clerk a library card (see Library cards) |
/clerk/callback |
Finish this install's library card sign-in (see Signing in with a library card) |
bookclerkd serves index.html for these paths, so a hard refresh on
/library loads the app instead of a 404. Assets still come from
ui/dist, and unknown paths get a branded 404.
- Only
/invite?ticket=claims an invite. On any other path, including/discover, theticketis ignored and dropped from the address. - A missing, invalid, expired or used ticket gets a branded 400 or 410 page instead of the form.
- The invite page is sent with
Cache-Control: no-store. - After a claim, the address becomes
/(without the ticket), so the user'sdefault_viewapplies.
On /, the web app opens the user's default_view: discover (the
default), wishlist, library or accounts. A deep link such as
/library wins over it, and the header logo goes to the start page.
Change it with Preferences in the header, or:
PATCH /api/preferences
Content-Type: application/json
{ "default_view": "library" }
It is stored per user (subject user:{id} for a linked user, portal:{identity_id} for an
unlinked identity, or operator).
The web app is designed in light; dark is an adaptation of the same ink, teal, brick and parchment palette.
- The theme is
system(the default),lightordark. - System follows
prefers-color-scheme. It uses light unless the OS explicitly asks for dark. - An explicit Light stays light on a dark OS.
- The sign-in screen stores the choice in
localStorage(bookclerk-theme). After sign-in it roams withPATCH /api/preferences{ "theme": "dark" }. - Branded daemon pages (invite, 404) can't read preferences, so they
follow
prefers-color-schemeonly.
- Shelves that scroll sideways, with catalog search across stores and autocomplete. Wishlist a title from a suggestion or a card.
- Live store prices load for visible cards only, in batches.
bestprefers the stores the viewer has linked. - On the wishlist cards show small profile pictures of the people who want each title.
- There is no approval or triage step.
- Your wishes: removing one removes your row and lowers or drops the title in the shared queue.
- Global queue (sidebar): one shared order for everyone, ranked by Discover taste with a strong boost for titles several people want. It is store-agnostic, and each row shows who wishlisted it.
The full library, in one scrolling list, for every signed-in role. Operators also see scan and acquire. Connecting stores stays in Accounts.
Link and revoke stores, and manage linked sign-in identities.
Revoke marks the account revoked (which stops its scans) and signs it out at the store (best effort). Then one atomic batch marks it revoked again, deletes its saved credentials and unlinks it, so the account is never left linked without credentials or unlinked with them. Books already in the library stay. If a step fails, the store stays listed and the page shows the error, so Revoke can be tried again.
A sign-in finishes by linking the account in one atomic batch that needs
its saved credentials (an account without them is never scanned). If
another sign-in of the same store account that the operator refused took
them back first, or a revoke ran meanwhile, nothing is linked: a password
sign-in answers 409 and asks you to sign in again, and a browser
(OAuth) sign-in, which finishes after its start route answered, leaves
the store unlisted and logs why.
- Profile: display name, email and picture. The role is shown; numeric user ids are not. Name and email save on blur or Enter, and Escape cancels.
- Security: password, named passkeys, authenticator app, linked identity providers, and Owner elevation.
- Player apps: player passwords for phone and car apps, each shown once (see Player apps).
- Sessions: browsers, desktop windows, library cards and player apps, each with Revoke. A library card shows the name its clerk gave itself; a player app shows a Player app badge; a desktop window shows Desktop app on <computer>, and revoking it signs that window out at its next launch.
Profile edits are self-service. Security and profile edits are hidden or disabled while impersonating.
Profile pictures. Clicking the picture offers a monogram, Gravatar
(when there is an email), SSO pictures or an upload. Automatic choice
prefers an upload, then the last SSO picture, then Gravatar
(https://www.gravatar.com/avatar/{sha256}?d=404), then the monogram.
Gravatar and SSO pictures are downloaded by Bookclerk and served from its
own address, so the browser never contacts Gravatar or the provider (see
Other images).
- Uploads are JPEG, PNG or WebP, saved as
$BOOKCLERK_FILES_DIR/avatars/{id}.{ext}. users.avatar_sourcestores an explicit choice:auto,monogram,gravatar,uploadorsso:{id}.
The operator adds the first Owner. The operator, Owners and Administrators create users with an invite link, change role and status, send a new invite, and reset passwords.
Who can grant which role:
- An Administrator adds Members only.
- An Owner adds Members and Administrators.
- The operator, or an elevated Owner, can grant any role.
Each row shows presence:
| Mark | Meaning |
|---|---|
| Dashed grey ring | Never signed in |
| Solid grey | Seen before; session expired |
| Brick (orange) | Signed in, idle |
| Teal | Active in the last 5 minutes or so |
| Logo waveform | Listening progress changed in that time, usually from a player integration |
| Brick X | Account disabled |
users.last_seen_at survives logout.
For the operator and Owners. In order: the second-factor policy, SSO into Bookclerk, and Bookclerk as an identity provider (with copyable discovery URLs and the client cards). Administrators can't change these.
The operator or an elevated Owner can act as another user. A brick
banner at the top names them (Impersonating Alex as Owner), with
Stop.
- The Settings tabs follow the impersonated role: User Management for Owners and Administrators, Sign-in for Owners.
- Server and Plugins stay operator-only until impersonation ends.
- Stop signs an elevated Owner back in as themselves, so ending elevation afterwards leaves them signed in rather than signed out.
For the operator, or an elevated Owner: listen addresses, sign-in, auto-acquire, isolation and jail limits, and turning plugins on.
Turning on a plugin shows a branded consent dialog. You can widen or narrow its grants, within the host's workerd and disk caps and its domain allowlists.
For the operator, or an elevated Owner: the libraries this server is a branch of.
- Join a library: the address, the fingerprint for a self-signed library, then a sign-in on that library. Or choose I have an invite.
- Leave library.
- Each library plugin that asks to run here, with a deny checkbox for each domain and binding, a switch to deny network, Approve (for the request shown, archive included) and Revoke. A refused approval shows the daemon's reason.
For the operator and Owners: Let new branches join, the address to join, and the fingerprint a joining operator checks.
- Branch invites come from Add a branch in User Management (and each user's own menu), and are shown once.
- On a fresh install, the operator first sees a welcome screen: Start a new library or Join a library. In the desktop app it opens on Sign in to your library with a library card instead. An install that holds a library card is no longer fresh.
The web app keeps one WebSocket open: GET /api/live, subprotocol
bookclerk-live.v1. It names topics whose data changed: library,
jobs, deliveries, nodes, config, consents, libraries,
users, discover, playback and notifications. Status, Library,
Discover, Settings → Nodes, User Management, Settings → Library and the
notification bell re-read their data when told.
- The socket carries topic names only.
- It needs an exact
Originmatch and a signed-in session, and is scoped to the caller's role. - While it is down, screens poll on their old timers, and the client reconnects with backoff from 1 to 30 seconds.
- The Vite dev server proxies it (
/api/livewithws: true).
Details: Node API and the live socket.
- Security checklist: sign-in settings for a public server.
- Managing plugins: turning plugins on and approving them.
- A future plugin browser is sketched in Plugin registry. Today, plugins are managed in Settings and the CLI; see Plugins.
Source: docs/server/sign-in.md at main · View as Markdown