qBittorrent Web API Authentication Methods: Cookie, Basic Auth, and Bearer Tokens

qBittorrent’s Web API supports three authentication methods: cookie-based sessions created via the /api/v2/auth/login endpoint, HTTP Basic authentication using Base64-encoded credentials, and Bearer token authentication with API keys generated through the rotateAPIKey endpoint.

The qBittorrent Web API provides programmatic control over one of the most popular open-source BitTorrent clients. Understanding the available qBittorrent Web API authentication methods is essential for building secure automation scripts and third-party integrations. This guide examines the implementation details in the qBittorrent source code to help you choose the right approach for your application.

Cookie-Based Session Authentication

The most common authentication method uses server-side sessions established through a dedicated login endpoint. When you submit a POST request to /api/v2/auth/login with username and password parameters, the server validates the credentials and returns an authentication cookie containing the Session ID (SID).

According to the source in src/webui/webapplication.cpp, this endpoint is declared at line 176 via declarePublicAPI(u"auth/login"_s). The AuthController class in src/webui/api/authcontroller.cpp handles the actual credential validation. Once authenticated, you must include the cookie in subsequent requests to maintain the session state.

# Login and save cookie

curl -i -c cookies.txt -d "username=admin&password=secret" \
     http://localhost:8080/api/v2/auth/login

# Use cookie for subsequent calls

curl -b cookies.txt http://localhost:8080/api/v2/torrents/info

HTTP Basic Authentication

For simpler integrations that do not require persistent session management, qBittorrent supports HTTP Basic authentication via the Authorization header. This method encodes the username and password in Base64 and transmits them with each request.

In src/webui/webapplication.cpp at line 81, the server defines the scheme constant as const QString BASIC_AUTH = u"Basic"_s. When the header Authorization: Basic <base64(username:password)> is present, the validateBasicAuth(authData) function (lines 768-770) validates the credentials against the configured user database and creates the same internal session object used by the cookie-based method.

# Basic Auth does not require prior login or cookie handling

curl -u admin:secret http://localhost:8080/api/v2/torrents/info

API Key (Bearer Token) Authentication

Modern integrations requiring stateless access can use API key authentication via Bearer tokens. This method is ideal for automation scripts that need persistent access without managing cookie lifecycles or exposing account passwords.

Generating API Keys

Generate a new key by calling /api/v2/app/rotateAPIKey while authenticated via cookie or Basic Auth. This endpoint is implemented in src/webui/api/appcontroller.cpp. The server returns a unique key that can be used indefinitely until explicitly revoked via /api/v2/app/deleteAPIKey.

Implementation Details

When using Bearer tokens, include the key in the request header as Authorization: Bearer <API_KEY>. In src/webui/webapplication.cpp (lines 656-664), the server detects this scheme using the constant const QString BEARER_AUTH = u"Bearer"_s. Upon validation, it instantiates an APIKeyBasedWebSession object, defined in src/webui/websession.cpp at lines 42-43, which represents a stateless authentication context separate from traditional user sessions.

# Generate API key (requires existing authentication)

curl -i -b cookies.txt http://localhost:8080/api/v2/app/rotateAPIKey

# Use the returned key

API_KEY="a1b2c3d4e5f6..."
curl -H "Authorization: Bearer $API_KEY" \
     http://localhost:8080/api/v2/torrents/info

Security Mechanisms and IP Whitelisting

Beyond credential validation, qBittorrent implements defense-in-depth measures. The server may enforce an IP-subnet whitelist for authentication attempts, configured via the m_authSubnetWhitelist member in src/webui/webapplication.cpp (lines 475-485).

Additionally, the system tracks failed login attempts in src/webui/webapplication.cpp and may trigger temporary IP bans after multiple failures, logging "WebAPI login failure" messages to prevent brute-force attacks.

Complete Code Examples

Here are complete implementations for all three authentication methods:

# Method 1: Cookie-based session

curl -i -c cookies.txt -d "username=admin&password=secret" \
     http://localhost:8080/api/v2/auth/login
curl -b cookies.txt http://localhost:8080/api/v2/torrents/info

# Method 2: HTTP Basic authentication

curl -u admin:secret http://localhost:8080/api/v2/torrents/info

# Method 3: Bearer token (API Key)

curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
     http://localhost:8080/api/v2/torrents/info

Summary

• Cookie-based sessions require a POST to /api/v2/auth/login and persistent cookie storage using the SID value
• HTTP Basic Auth transmits Base64-encoded credentials in the Authorization header and is handled by validateBasicAuth(authData) in webapplication.cpp
• Bearer tokens provide stateless authentication via API keys created by rotateAPIKey, using the APIKeyBasedWebSession class
• IP whitelisting and brute-force protection are enforced in src/webui/webapplication.cpp to secure the authentication layer

Frequently Asked Questions

Which authentication method is most secure for automated scripts?

API key authentication via Bearer tokens is recommended for automation because it provides stateless, revocable access without transmitting account passwords in every request. According to the implementation in websession.cpp, API keys create isolated APIKeyBasedWebSession objects that can be deleted independently of user credentials, limiting exposure if a key is compromised.

Why does my qBittorrent API request return 403 Forbidden?

A 403 response typically indicates authentication failure. Verify that your session cookie has not expired, your Basic Auth header uses correct Base64 encoding, or your API key is valid. Also check if your client IP address falls within the configured m_authSubnetWhitelist defined in webapplication.cpp (lines 475-485), as subnet restrictions will reject otherwise valid credentials from unauthorized networks.

Can I mix authentication methods when calling the qBittorrent Web API?

While the server will accept requests using any valid authentication method, you should not mix methods within a single logical session. The dispatcher in webapplication.cpp (lines 656-664) prioritizes Bearer tokens when present, then falls back to Basic Auth, then checks for valid session cookies. Each method creates distinct session objects, so relying on one consistently prevents authorization edge cases.

Where does qBittorrent validate API credentials in the source code?

Primary validation occurs in src/webui/webapplication.cpp. The validateBasicAuth(authData) function handles Basic Auth at lines 768-770. Cookie-based sessions are validated against the session store, while API keys are verified when the Authorization: Bearer header triggers the creation of an APIKeyBasedWebSession in websession.cpp. The AuthController class in src/webui/api/authcontroller.cpp specifically manages the /auth/login endpoint for cookie-based authentication.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}