Support qBittorrent 5.2 API-key authentication (closes ManiMatter#353)

qBittorrent 5.2 added stateless API-key auth (Authorization: Bearer),
which lets users avoid storing username/password credentials. This adds
an optional `api_key` field to qBittorrent clients and makes it the
recommended auth path; username/password remain as a legacy fallback for
qBit < 5.2.

- QbitClient accepts `api_key`; a new `_auth_kwargs()` helper returns the
  Bearer header in key mode or the SID cookie in password mode, used at
  every authenticated request site.
- refresh_cookie() and check_qbit_reachability() branch for key mode:
  login is skipped (qBit rejects /auth/login under key auth) and
  reachability probes /app/version with the Bearer header instead. A
  bad key or a <5.2 server both surface a clear tip and degrade instead
  of crashing.
- If both api_key and username/password are set, the key wins (mirrors
  qBit), logged once at init.
- Redact `Authorization` in sanitize_kwargs so the token never leaks in
  DEBUG logs.
- Docs (config example, README) present api_key as recommended, creds as
  legacy. Tests cover header-vs-cookie selection, login skip, precedence,
  and the 403 degrade path.

Author: jrhager84

README.md

@@ -288,8 +288,9 @@ services:
       # --- Download Clients ---
       QBITTORRENT: >
         - base_url: "http://qbittorrent:8080"
-          # username: "$QBIT_USERNAME" # (optional -> if not provided, assuming not needed)
-          # password: "$QBIT_PASSWORD" # (optional -> if not provided, assuming not needed)
+          # api_key: "$QBIT_API_KEY" # (recommended -> requires qBittorrent 5.2.0+; takes precedence over username/password)
+          # username: "$QBIT_USERNAME" # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
+          # password: "$QBIT_PASSWORD" # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
           name: "qBittorrent 1" # (optional -> if not provided, assuming "qBittorrent". Must correspond with what is specified in your *arr as download client name)
         - base_url: "http://qbittorrent:8080"
           name: "qBittorrent 2" 
@@ -704,8 +705,9 @@ Supported download clients: **qBittorrent** and **SABnzbd**.
 -   Type: List of qbit instances
 -   Keys per instance
     - base_url: URL under which the qbit can be reached (mandatory)
-    - username: Optional - only needed if your qbit requires authentication (which you may not need if you have configured qbit in a way that it disables it for local connections)
-    - password: Optional - see above
+    - api_key: Recommended - qBittorrent API key (requires qBittorrent 5.2.0 or newer; generate it under Web UI settings). Authenticates without storing credentials, and takes precedence over username/password if both are set.
+    - username: Legacy - only for qBittorrent < 5.2, or if your qbit requires authentication (which you may not need if qbit disables it for local connections). Ignored when api_key is set.
+    - password: Legacy - see above
     - name: Optional. Needs to correspond with the name that you have set up in your Arr instance. Defaults to "qBittorrent"
 
 #### SABNZBD

config/config_example.yaml

@@ -69,8 +69,9 @@ instances:
 download_clients:
   qbittorrent:
     - base_url: "http://qbittorrent:8080" # You can use decluttarr without qbit (not all features available, see readme).
-      # username: xxxx # (optional -> if not provided, assuming not needed)
-      # password: xxxx # (optional -> if not provided, assuming not needed)
+      # api_key: "qbt_xxxx" # (recommended -> requires qBittorrent 5.2.0+; generate under Web UI settings. Takes precedence over username/password.)
+      # username: xxxx # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
+      # password: xxxx # (legacy -> for qBittorrent < 5.2; ignored if api_key is set)
       # name: "qBittorrent" # (optional -> if not provided, assuming "qBittorrent". Must correspond with what is specified in your *arr as download client name)
   # sabnzbd:
   #   - base_url: "http://sabnzbd:8080" # SABnzbd server URL

src/settings/_download_clients_qbit.py

@@ -58,6 +58,7 @@ def __init__(
         username: str = None,
         password: str = None,
         name: str = None,
+        api_key: str = None,
     ):
         self.settings = settings
         if not base_url:
@@ -70,13 +71,20 @@ def __init__(
         self.min_version = MinVersions.qbittorrent
         self.username = username
         self.password = password
+        # Treat an empty/whitespace api_key as unset so it falls back to password auth.
+        self.api_key = api_key.strip() if isinstance(api_key, str) else api_key
         self.name = name
         if not self.name:
             logger.verbose(
                 "No name provided for qbittorrent client, assuming 'qBitorrent'. If the name used in your *arr is different, please correct either the name in your *arr, or set the name in your config",
             )
             self.name = "qBittorrent"
 
+        if self.api_key and (username or password):
+            logger.info(
+                f"qBittorrent '{self.name}': both api_key and username/password provided; using api_key (credentials ignored).",
+            )
+
         self._remove_none_attributes()
 
     def _remove_none_attributes(self):
@@ -85,8 +93,27 @@ def _remove_none_attributes(self):
             if getattr(self, attr) is None:
                 delattr(self, attr)
 
+    def _auth_kwargs(self) -> dict:
+        """Return the make_request auth kwargs for the configured mode.
+
+        Key mode (qBit >= 5.2): stateless 'Authorization: Bearer' header on every
+        request. Password mode (legacy): the session SID cookie from refresh_cookie().
+        Must stay a method (not cached) so password mode reads the freshly
+        refreshed self.cookie each cycle.
+        """
+        api_key = getattr(self, "api_key", None)
+        if api_key:
+            return {"headers": {"Authorization": f"Bearer {api_key}"}}
+        return {"cookies": getattr(self, "cookie", None)}
+
     async def refresh_cookie(self):
         """Refresh the qBittorrent session cookie."""
+        if getattr(self, "api_key", None):
+            # Key mode is stateless; qBit rejects /auth/login under API-key auth.
+            logger.debug(
+                "_download_clients_qBit.py/refresh_cookie: API-key mode, skipping login",
+            )
+            return
 
         def _connection_error():
             error = "Login failed."
@@ -144,7 +171,7 @@ async def fetch_version(self):
             "get",
             endpoint,
             self.settings,
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )
         self.version = response.text[1:]  # Remove the '_v' prefix
         logger.debug(
@@ -172,7 +199,7 @@ async def create_tag(self, tag: str):
             "_download_clients_qBit.py/create_tag: Checking if tag '{tag}' exists (and creating it if not)",
         )
         url = f"{self.api_url}/torrents/tags"
-        response = await make_request("get", url, self.settings, cookies=self.cookie)
+        response = await make_request("get", url, self.settings, **self._auth_kwargs())
         current_tags = response.json()
 
         if tag not in current_tags:
@@ -183,7 +210,7 @@ async def create_tag(self, tag: str):
                 self.api_url + "/torrents/createTags",
                 self.settings,
                 data=data,
-                cookies=self.cookie,
+                **self._auth_kwargs(),
             )
 
     async def create_required_tags(self):
@@ -207,7 +234,7 @@ async def set_unwanted_folder(self):
                 "get",
                 endpoint,
                 self.settings,
-                cookies=self.cookie,
+                **self._auth_kwargs(),
             )
             qbit_settings = response.json()
 
@@ -221,33 +248,51 @@ async def set_unwanted_folder(self):
                     self.api_url + "/app/setPreferences",
                     self.settings,
                     data=data,
-                    cookies=self.cookie,
+                    **self._auth_kwargs(),
                 )
 
     async def check_qbit_reachability(self):
-        """Check if the qBittorrent URL is reachable."""
+        """Check if the qBittorrent URL is reachable (and the credentials work)."""
         try:
             logger.debug(
                 "_download_clients_qBit.py/check_qbit_reachability: Checking if qbit is reachable",
             )
-            endpoint = f"{self.api_url}/auth/login"
-            data = {
-                "username": getattr(self, "username", ""),
-                "password": getattr(self, "password", ""),
-            }
-            headers = {"content-type": "application/x-www-form-urlencoded"}
-            await make_request(
-                "post",
-                endpoint,
-                self.settings,
-                data=data,
-                headers=headers,
-                log_error=False,
-                ignore_test_run=True,
-            )
+            if getattr(self, "api_key", None):
+                # Key mode: qBit rejects /auth/login, so probe a normal authed
+                # endpoint with the Bearer header instead.
+                await make_request(
+                    "get",
+                    f"{self.api_url}/app/version",
+                    self.settings,
+                    log_error=False,
+                    ignore_test_run=True,
+                    **self._auth_kwargs(),
+                )
+            else:
+                endpoint = f"{self.api_url}/auth/login"
+                data = {
+                    "username": getattr(self, "username", ""),
+                    "password": getattr(self, "password", ""),
+                }
+                headers = {"content-type": "application/x-www-form-urlencoded"}
+                await make_request(
+                    "post",
+                    endpoint,
+                    self.settings,
+                    data=data,
+                    headers=headers,
+                    log_error=False,
+                    ignore_test_run=True,
+                )
 
         except Exception as e:  # noqa: BLE001
-            tip = "💡 Tip: Did you specify the URL (and username/password if required) correctly?"
+            if getattr(self, "api_key", None):
+                tip = (
+                    "💡 Tip: Is the qBittorrent API key correct, and is your qBittorrent "
+                    "at least v5.2.0? API-key auth requires qBit 5.2+ (WebAPI 2.14.1+)."
+                )
+            else:
+                tip = "💡 Tip: Did you specify the URL (and username/password if required) correctly?"
             if str(e) != self.last_error:  # Only report new failure modes in full
                 logger.error(f"-- | qBittorrent\n❗️ {e}\n{tip}\n")
             raise QbitError(e, tip=tip) from e
@@ -263,7 +308,7 @@ async def check_connected(self):
                     "get",
                     self.api_url + "/sync/maindata",
                     self.settings,
-                    cookies=self.cookie,
+                    **self._auth_kwargs(),
                 )
             ).json()
         )["server_state"]["connection_status"]
@@ -378,7 +423,7 @@ async def set_tag(self, tags, hashes):
             self.api_url + "/torrents/addTags",
             self.settings,
             data=data,
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )
 
     async def fetch_download_progress(self, download_id):
@@ -401,7 +446,7 @@ async def get_qbit_items(self, hashes: list[str] | str | None = None) -> list[di
             endpoint=f"{self.api_url}/torrents/info",
             settings=self.settings,
             params=None,  # Retrieve all torrents
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )
 
         all_items = response.json()
@@ -423,7 +468,7 @@ async def get_torrent_properties(self, qbit_hash):
             self.api_url + "/torrents/properties",
             self.settings,
             params=params,
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )
         return response.json()
 
@@ -435,7 +480,7 @@ async def get_torrent_files(self, download_id):
             endpoint=self.api_url + "/torrents/files",
             settings=self.settings,
             params={"hash": download_id.lower()},
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )
         return response.json()
 
@@ -453,7 +498,7 @@ async def set_torrent_file_priority(self, download_id, file_id, priority=0):
             self.api_url + "/torrents/filePrio",
             self.settings,
             data=data,
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )
 
     async def set_bandwidth_usage(self):
@@ -463,7 +508,7 @@ async def set_bandwidth_usage(self):
             method="get",
             endpoint=self.api_url + "/transfer/info",
             settings=self.settings,
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )
         records = extract_json_from_response(response)
         limit = records["dl_rate_limit"]
@@ -500,5 +545,5 @@ async def remove_download(self, download_hash: str, delete_files: bool = True):
             f"{self.api_url}/torrents/delete",
             self.settings,
             data=data,
-            cookies=self.cookie,
+            **self._auth_kwargs(),
         )

src/utils/common.py

@@ -26,7 +26,14 @@ def sanitize_kwargs(data):
         for key, value in data.items():
             if (
                 key.lower()
-                in {"username", "password", "x-api-key", "apikey", "cookies"}
+                in {
+                    "username",
+                    "password",
+                    "x-api-key",
+                    "apikey",
+                    "cookies",
+                    "authorization",
+                }
                 and value
             ):
                 redacted[key] = "[**redacted**]"