From 5b3df2a463f83e8ff396261168b27de0bba807b9 Mon Sep 17 00:00:00 2001 From: CaliBrain Date: Thu, 20 Aug 2026 19:29:55 -0400 Subject: [PATCH] docs(hardcover): list the API key scopes Shelfmark needs (#1243) Hardcover's August 2026 token system replaced blanket access with per-token scopes, and nothing in the docs said which ones Shelfmark actually uses. A key missing write:library or write:lists still passes Test Connection -- the reading-status and auto-remove-on-download calls just fail silently afterwards. Verified against a live hc_pat_ key: every scope in the table backs a query or mutation the provider really issues, and the omitted ones (journal, goals, reviews, prompts, notifications, account) are absent from the provider entirely. Refs #1240 --- readme.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/readme.md b/readme.md index aa5434df..1be0e0af 100644 --- a/readme.md +++ b/readme.md @@ -95,6 +95,30 @@ volumes: - Aggregates releases from multiple configured sources - Full audiobook support +### Hardcover API Key + +Hardcover powers metadata search in Universal mode. Create a token at +[hardcover.app/account/api](https://hardcover.app/account/api) — current keys start with `hc_pat_` +and are far shorter than the JWTs Hardcover issued before August 2026. + +Tick these seven scopes on the token screen: + +| Scope | Used for | +|-------|----------| +| `read:catalog` | Metadata search, plus book, edition, author and series lookups | +| `read:library` | Your reading status and shelf counts | +| `read:lists` | Your lists and the books on them | +| `read:me:content` | Test Connection and the "Connected as" label | +| `read:users` | Usernames shown alongside lists | +| `write:library` | Setting a book's reading status from Shelfmark | +| `write:lists` | Adding and removing books from lists, including auto-remove on download | + +The two `write:` scopes matter only if you set reading status from Shelfmark or leave +**Auto-Remove from List on Download** enabled (it is on by default) — without them those actions +fail silently. Everything else Hardcover offers (journal, goals, reviews, prompts, notifications, +account) can stay unticked. The `all` scope works too, but it grants full account access including +deletion, so prefer the list above. + ### Environment Variables Environment variables work for initial setup and Docker deployments. They serve as defaults that can be overridden in the web interface.