fix: Propagate API token to custom HTTP clients

Author: vdusek

docs/03_guides/code/05_custom_http_client_async.py

@@ -35,6 +35,10 @@ async def call(
     ) -> HttpResponse:
         timeout_secs = self._compute_timeout(timeout, attempt=1) or 0
 
+        # Merge the client's default headers (including authorization)
+        # with the per-request ones.
+        headers = {**self._headers, **(headers or {})}
+
         # httpx.Response satisfies the HttpResponse protocol,
         # so it can be returned directly.
         return await self._client.request(

docs/03_guides/code/05_custom_http_client_sync.py

@@ -34,6 +34,10 @@ def call(
     ) -> HttpResponse:
         timeout_secs = self._compute_timeout(timeout, attempt=1) or 0
 
+        # Merge the client's default headers (including authorization)
+        # with the per-request ones.
+        headers = {**self._headers, **(headers or {})}
+
         # httpx.Response satisfies the HttpResponse protocol,
         # so it can be returned directly.
         return self._client.request(

src/apify_client/_apify_client.py

@@ -227,7 +227,7 @@ def with_custom_http_client(
 
         Use this alternative constructor when you want to provide your own HTTP client implementation
         instead of the default one. The custom client is responsible for its own configuration
-        (retries, timeouts, headers, etc.).
+        (retries, timeouts, etc.); only the token is applied to it, as described below.
 
         ### Usage
 
@@ -246,12 +246,16 @@ def call(self, *, method, url, **kwargs) -> HttpResponse:
         ```
 
         Args:
-            token: The Apify API token.
+            token: The Apify API token. It is set as the `Authorization` header on the custom client,
+                unless the client already has one configured.
             api_url: The URL of the Apify API server to connect to. Defaults to https://api.apify.com.
             api_public_url: The globally accessible URL of the Apify API server. Defaults to https://api.apify.com.
             http_client: A custom HTTP client instance extending `HttpClient`.
         """
         instance = cls(token=token, api_url=api_url, api_public_url=api_public_url)
+        client_headers = http_client._headers  # noqa: SLF001
+        if token is not None and not any(key.title() == 'Authorization' for key in client_headers):
+            client_headers['Authorization'] = f'Bearer {token}'
         instance._http_client = http_client
         return instance
 
@@ -586,7 +590,7 @@ def with_custom_http_client(
 
         Use this alternative constructor when you want to provide your own HTTP client implementation
         instead of the default one. The custom client is responsible for its own configuration
-        (retries, timeouts, headers, etc.).
+        (retries, timeouts, etc.); only the token is applied to it, as described below.
 
         ### Usage
 
@@ -605,12 +609,16 @@ async def call(self, *, method, url, **kwargs) -> HttpResponse:
         ```
 
         Args:
-            token: The Apify API token.
+            token: The Apify API token. It is set as the `Authorization` header on the custom client,
+                unless the client already has one configured.
             api_url: The URL of the Apify API server to connect to. Defaults to https://api.apify.com.
             api_public_url: The globally accessible URL of the Apify API server. Defaults to https://api.apify.com.
             http_client: A custom HTTP client instance extending `HttpClientAsync`.
         """
         instance = cls(token=token, api_url=api_url, api_public_url=api_public_url)
+        client_headers = http_client._headers  # noqa: SLF001
+        if token is not None and not any(key.title() == 'Authorization' for key in client_headers):
+            client_headers['Authorization'] = f'Bearer {token}'
         instance._http_client = http_client
         return instance
 

src/apify_client/http_clients/_base.py

@@ -207,11 +207,15 @@ def _prepare_request_call(
         data: str | bytes | bytearray | None = None,
         json: JsonSerializable | None = None,
     ) -> tuple[dict[str, str], dict[str, Any] | None, bytes | None]:
-        """Prepare headers, params, and body for an HTTP request. Serializes JSON and compresses the body."""
+        """Prepare headers, params, and body for an HTTP request.
+
+        Merges the client's default headers (including authorization) with per-request headers,
+        serializes JSON and compresses the body.
+        """
         if json is not None and data is not None:
             raise ValueError('Cannot pass both "json" and "data" parameters at the same time!')
 
-        headers = dict(headers) if headers else {}
+        headers = {**self._headers, **(headers or {})}
 
         # Dump JSON data to string so it can be compressed.
         if json is not None:
@@ -252,6 +256,10 @@ class HttpClient(HttpClientBase, ABC):
     Extend this class to create a custom synchronous HTTP client. Override the `call` method
     with your implementation. Helper methods from the base class are available for request
     preparation, URL building, and parameter parsing.
+
+    Implementations must send the client's default headers from `self._headers` with every request,
+    otherwise the `Authorization` header never reaches the API. The `_prepare_request_call` helper
+    merges them into the per-request headers automatically.
     """
 
     @abstractmethod

tests/unit/test_http_clients.py

@@ -279,11 +279,13 @@ def compressor_case(request: pytest.FixtureRequest) -> tuple:
 
 
 def test_prepare_request_call_basic() -> None:
-    """Test _prepare_request_call with basic parameters."""
-    client = _ConcreteHttpClient()
+    """Test _prepare_request_call returns the client default headers when no per-request values are given."""
+    client = _ConcreteHttpClient(token='test_token')
 
     headers, params, data = client._prepare_request_call()
-    assert headers == {}
+    assert headers == client._headers
+    assert headers is not client._headers
+    assert headers['Authorization'] == 'Bearer test_token'
     assert params is None
     assert data is None
 

tests/unit/test_pluggable_http_client.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+import json as jsonlib
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
+import impit
 import pytest
+from werkzeug import Request, Response
 
 import apify_client as apify_client_module
 import apify_client.http_clients as http_clients_module
@@ -423,3 +426,125 @@ async def call(self, *, method: str, url: str, **kwargs: Any) -> HttpResponse:
 
     assert result is not None
     assert result['data']['id'] == 'test-dataset'
+
+
+class PreparingHttpClient(HttpClient):
+    """A custom sync HTTP client that sends requests prepared by the base-class helpers."""
+
+    def __init__(self, token: str | None = None) -> None:
+        super().__init__(token=token)
+        self._impit_client = impit.Client()
+
+    def call(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        data: str | bytes | bytearray | None = None,
+        json: Any = None,
+        **_kwargs: Any,
+    ) -> HttpResponse:
+        headers, params, content = self._prepare_request_call(headers=headers, params=params, data=data, json=json)
+        url = self._build_url_with_params(url, params=params)
+        return self._impit_client.request(method=method, url=url, headers=headers, content=content)
+
+
+class PreparingHttpClientAsync(HttpClientAsync):
+    """A custom async HTTP client that sends requests prepared by the base-class helpers."""
+
+    def __init__(self, token: str | None = None) -> None:
+        super().__init__(token=token)
+        self._impit_client = impit.AsyncClient()
+
+    async def call(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        data: str | bytes | bytearray | None = None,
+        json: Any = None,
+        **_kwargs: Any,
+    ) -> HttpResponse:
+        headers, params, content = self._prepare_request_call(headers=headers, params=params, data=data, json=json)
+        url = self._build_url_with_params(url, params=params)
+        return await self._impit_client.request(method=method, url=url, headers=headers, content=content)
+
+
+def _echo_headers(request: Request) -> Response:
+    """Respond with the received request headers so tests can assert on them."""
+    return Response(
+        response=jsonlib.dumps({'received_headers': dict(request.headers)}),
+        status=200,
+        content_type='application/json',
+    )
+
+
+def test_custom_http_client_sends_token_from_classmethod(httpserver: HTTPServer) -> None:
+    """Token passed to with_custom_http_client is sent as the Authorization header by the custom client."""
+    httpserver.expect_request('/v2/datasets/test-dataset').respond_with_handler(_echo_headers)
+
+    api_url = httpserver.url_for('/').removesuffix('/')
+    client = ApifyClient.with_custom_http_client(
+        token='test_token',
+        api_url=api_url,
+        http_client=PreparingHttpClient(),
+    )
+
+    result = client.dataset('test-dataset')._get(timeout='short')
+
+    assert result is not None
+    assert result['received_headers']['Authorization'] == 'Bearer test_token'
+
+
+async def test_custom_http_client_async_sends_token_from_classmethod(httpserver: HTTPServer) -> None:
+    """Token passed to async with_custom_http_client is sent as the Authorization header by the custom client."""
+    httpserver.expect_request('/v2/datasets/test-dataset').respond_with_handler(_echo_headers)
+
+    api_url = httpserver.url_for('/').removesuffix('/')
+    client = ApifyClientAsync.with_custom_http_client(
+        token='test_token',
+        api_url=api_url,
+        http_client=PreparingHttpClientAsync(),
+    )
+
+    result = await client.dataset('test-dataset')._get(timeout='short')
+
+    assert result is not None
+    assert result['received_headers']['Authorization'] == 'Bearer test_token'
+
+
+def test_custom_http_client_impit_instance_sends_token(httpserver: HTTPServer) -> None:
+    """Token from with_custom_http_client reaches the wire even for a pre-built tokenless ImpitHttpClient."""
+    httpserver.expect_request('/v2/datasets/test-dataset').respond_with_handler(_echo_headers)
+
+    api_url = httpserver.url_for('/').removesuffix('/')
+    client = ApifyClient.with_custom_http_client(token='test_token', api_url=api_url, http_client=ImpitHttpClient())
+
+    result = client.dataset('test-dataset')._get(timeout='short')
+
+    assert result is not None
+    assert result['received_headers']['Authorization'] == 'Bearer test_token'
+
+
+def test_custom_http_client_keeps_own_token() -> None:
+    """An Authorization header configured on the custom client itself is not overridden by with_custom_http_client."""
+    http_client = PreparingHttpClient(token='client_token')
+
+    ApifyClient.with_custom_http_client(token='outer_token', http_client=http_client)
+
+    assert http_client._headers['Authorization'] == 'Bearer client_token'
+
+
+def test_custom_http_client_keeps_differently_cased_authorization() -> None:
+    """A lowercase 'authorization' header on the custom client is not duplicated by the token injection."""
+    http_client = PreparingHttpClient()
+    http_client._headers['authorization'] = 'Bearer client_token'
+
+    ApifyClient.with_custom_http_client(token='outer_token', http_client=http_client)
+
+    assert 'Authorization' not in http_client._headers
+    assert http_client._headers['authorization'] == 'Bearer client_token'