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

> Discover qBittorrent Web API authentication methods including cookie sessions, basic auth, and bearer tokens. Securely manage your qBittorrent client programmatically.

- Repository: [qBittorrent project/qBittorrent](https://github.com/qbittorrent/qBittorrent)
- Tags: api-reference
- Published: 2026-05-05

---

**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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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.

```bash

# 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`](https://github.com/qbittorrent/qBittorrent/blob/main/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.

```bash

# 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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/websession.cpp) at lines 42-43, which represents a stateless authentication context separate from traditional user sessions.

```bash

# 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`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/webapplication.cpp) (lines 475-485).

Additionally, the system tracks failed login attempts in [`src/webui/webapplication.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/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:

```bash

# 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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/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`](https://github.com/qbittorrent/qBittorrent/blob/main/websession.cpp). The `AuthController` class in [`src/webui/api/authcontroller.cpp`](https://github.com/qbittorrent/qBittorrent/blob/main/src/webui/api/authcontroller.cpp) specifically manages the `/auth/login` endpoint for cookie-based authentication.