API key authentication for the existing JSON API (revisiting #833)

[gavinmcfall]

Shelfmark's frontend already drives a complete JSON API under /api/*, but every route requires a browser session cookie. #833 asked for a public API with bearer tokens and was closed as not planned; I'd like to propose a much narrower version and check whether it fits the project's scope before opening a PR.

Proposal: personal API keys as an authentication method, nothing else.

• Users create named keys from their own settings (user menu → Settings → API keys; admins do it from their row under Users & Requests); only a SHA-256 hash is stored, the key is shown once. Optional expiry.
• A key is sent as Authorization: Bearer smk_… (or X-Api-Key) and acts exactly as the user who created it — same role, request policy and settings. No scopes.
• A before_request middleware mirrors the existing proxy-auth middleware: it resolves the key into the same session fields every guard already reads, for that request only, with no cookie emitted and any incoming cookie ignored. No existing route or guard changes.
• Only smk_-prefixed credentials count as key attempts. A Bearer token that a reverse proxy forwards (oauth2-proxy, Authelia, forwardAuth id tokens) is ignored by the middleware and the request continues with normal session/proxy auth, so existing deployments are unaffected by an upgrade.
• Admins can see and revoke any user's keys from the user editor, and a Security-tab switch ("Allow personal API keys", default on) turns keys off globally.
• No new domain endpoints, no webhooks, no OpenAPI — the API surface is unchanged.

Why: self-hosters increasingly want to call Shelfmark from scripts, dashboards (Glance), and assistants. Today the only options are scraping, sharing a password, or replaying a cookie.

I have this working on a branch with tests for the store, service, middleware and routes, plus a short docs page: https://github.com/gavinmcfall/shelfmark/tree/feat/api-keys (diff: main...gavinmcfall:shelfmark:feat/api-keys). Happy to open the PR if this is in scope, or to drop it if not.

[calibrain]

To keep it even simpler, do you think we can make it even easier and you set the API key through an env variable ? If set, it will accept both cookie OR the hard coded API key ?

How important is multi user support for your use case ?

[gavinmcfall]

Multi-user isn't important for my use case — one automation (an assistant driving search → download) acting as one account. Happy to simplify to your shape.

Proposed semantics, so we agree before I rework the PR:

• API_KEY env var (name your call). When unset, nothing changes.
• When set, a request carrying Authorization: Bearer <that value> (or X-Api-Key) is authenticated as the builtin admin for that request only — cookie sessions keep working exactly as today, so it's cookie OR key.
• Constant-time compare; identity resolved per request into the same session fields the guards already read (the proxy-auth pattern), no cookie emitted on keyed requests, and any incoming cookie ignored on a keyed request. A wrong key is a plain 401; a Bearer value that isn't the configured key is ignored so proxies forwarding their own tokens are unaffected.
• No table, no UI, no per-user keys, no Security-tab switch — the env var's presence is the switch; rotation is "change the env var and restart".

One question: in OIDC/proxy installs the builtin admin may not exist (has_local_password_admin is false), so "act as admin" needs a target identity. Simplest is "act as the first admin user in users.db"; or an optional API_KEY_USER=<username> to pick the account the key acts as. Which do you prefer?

If that matches what you had in mind I'll rework #1353 down to that (or open a fresh PR if you'd rather keep the history clean). Per-user keys can be layered on later if anyone actually asks for them; no need to carry that now.

[calibrain]

Sounds good, lets keep it simple, just use the first admin in the db is good enough
I think its easier to abandon 1353 and open a smaller cleaner one

Thank you !

[gavinmcfall]

Done: #1366 is the smaller one (two commits: the feature and its docs), acting as the first admin in the db as agreed; #1353 closed as superseded.