diff --git a/apps/web/src/pages/SlskdSettings.tsx b/apps/web/src/pages/SlskdSettings.tsx
index a7d0c73d..5a2a3082 100644
--- a/apps/web/src/pages/SlskdSettings.tsx
+++ b/apps/web/src/pages/SlskdSettings.tsx
@@ -71,9 +71,11 @@ export function SlskdConnectionForm({
slskd is both the search source and the downloader. Soulseek login
- stays in slskd. Dewarr uses a read-write API key, reads the download
- folder, and checks whether Dewarr can access the same path. If the
- paths differ, configure the folder mapping under Download clients.
+ stays in slskd. Dewarr needs an API key with the administrator role,
+ because slskd only shares its download folder with administrator keys.
+ Dewarr reads that folder and checks whether it can reach the same
+ path. If the paths differ, configure the folder mapping under Download
+ clients.
@@ -98,7 +100,7 @@ export function SlskdConnectionForm({
value={apiKey}
onChange={(event) => setApiKey(event.target.value)}
autoComplete="off"
- placeholder={value.has_api_key ? "••••••••" : "Read-write API key"}
+ placeholder={value.has_api_key ? "••••••••" : "Administrator API key"}
minLength={apiKey ? 16 : undefined}
maxLength={255}
/>
diff --git a/docs/DOWNLOAD-CLIENTS.md b/docs/DOWNLOAD-CLIENTS.md
index ec65c7a9..92d9724d 100644
--- a/docs/DOWNLOAD-CLIENTS.md
+++ b/docs/DOWNLOAD-CLIENTS.md
@@ -4,6 +4,21 @@ Settings → Download clients supports qBittorrent, Transmission, and Deluge, al
the existing Usenet clients. Save and test a connection, map its download folder to a
folder the worker can read. Torrent and Usenet sources use their respective default
client; Soulseek uses slskd. A sole enabled client of a type is the automatic default.
+
+slskd needs an API key with the **administrator** role. slskd only shares its download folder with
+administrator keys, and Dewarr needs that folder to import finished downloads. A read-write key passes the
+first checks and then fails with "slskd only shares its download folder with an administrator API key". In
+slskd's `slskd.yml`:
+
+```yaml
+web:
+ authentication:
+ api_keys:
+ dewarr:
+ key:
+ role: administrator
+ cidr: 192.168.0.0/16
+```
With multiple clients of the same type, choose the default in Settings → Download clients.
To disable any client, choose **Edit downloader**, clear **Enabled**, and save.
diff --git a/services/app/adapters/slskd.py b/services/app/adapters/slskd.py
index 1c163c2e..3534429d 100644
--- a/services/app/adapters/slskd.py
+++ b/services/app/adapters/slskd.py
@@ -412,9 +412,19 @@ async def request(self, method: str, path: str, **kwargs: Any) -> Any:
async def test(self) -> dict[str, str]:
application = await self.request("GET", "/application")
version = await self.request("GET", "/application/version")
+ try:
+ options = await self.request("GET", "/options")
+ except AdapterError as error:
+ # slskd 0.26 shows its options, with the download folder, only to administrator keys.
+ if error.kind is not FailureKind.AUTHENTICATION:
+ raise
+ raise AdapterError(
+ FailureKind.AUTHENTICATION,
+ "slskd only shares its download folder with an administrator API key. In slskd, "
+ "give this key the administrator role, then test again.",
+ ) from error
if not soulseek_connected(application):
raise AdapterError(FailureKind.UNAVAILABLE, "Soulseek is not connected in slskd")
- options = await self.request("GET", "/options")
downloads = ((options or {}).get("directories") or {}).get("downloads")
if not isinstance(downloads, str) or not absolute_download_root(downloads):
raise AdapterError(FailureKind.UNSUPPORTED, "slskd did not report a download directory")
diff --git a/tests/unit/test_slskd.py b/tests/unit/test_slskd.py
index 00a75faf..b08dc1ac 100644
--- a/tests/unit/test_slskd.py
+++ b/tests/unit/test_slskd.py
@@ -495,3 +495,24 @@ def handler(request: httpx.Request):
state = await client.batch("attempt-1", release)
assert state.state == "failed"
assert state.completed is False
+
+
+@pytest.mark.asyncio
+async def test_a_key_that_cannot_read_options_asks_for_an_administrator_key():
+ """slskd 0.26 answers /options with 403 for read-write keys."""
+
+ def handler(request: httpx.Request):
+ path = request.url.path
+ if path.endswith("/application"):
+ return httpx.Response(200, json={"server": {"state": "Connected, LoggedIn"}})
+ if path.endswith("/application/version"):
+ return httpx.Response(200, json="0.26.2.0")
+ return httpx.Response(403)
+
+ async with SlskdClient(
+ "http://slskd.test:5030", KEY, transport=httpx.MockTransport(handler)
+ ) as client:
+ with pytest.raises(AdapterError) as raised:
+ await client.test()
+ assert raised.value.kind is FailureKind.AUTHENTICATION
+ assert "administrator" in str(raised.value)