Cookies and custom auth

[AstraLuma]

Ok, so:

• Using AsyncClient
• Gave a CookieJar to the client
• Passing individual requests an Auth implementation to implement custom on-demand authentication

What I'm seeing is that cookies are being inconsistently set on requests? I was expecting global implicit cookies (that I'm responsible for serializing), but with log level DEBUG I'm seeing that cookies are only sent if I explicitly set them on each request. And even then, I can't seem to force cookies on the final re-request.

[AstraLuma]

I have learned that Request does not track cookies outside of the header, and that Auth implementations need to update it themselves.

[amasen02]

Why this happens under the hood

Two architectural design decisions in httpx explain both behaviors you observed:

---

1. client.send() does NOT merge client-level cookies

In httpx, Client.send(request) is designed to send the Request instance as-is, unmodified:

# Client.send docstring in httpx/_client.py:
"""
Send a request.
The request is sent as-is, unmodified.
Typically you'll want to build one with `Client.build_request()`
so that any client-level configuration is merged into the request...
"""

• When you call client.get(...) or client.post(...), client.build_request() is called internally, which executes self._merge_cookies(cookies) and bakes the cookie key-value pairs into request.headers["cookie"].
• If you manually instantiate httpx.Request(...) and pass it to client.send(request), request.headers never receives client.cookies.

---

2. _send_handling_auth does NOT re-run build_request()

When a custom Auth class yields a retry request inside its generator (auth_flow), httpx's auth loop runs:

# httpx/_client.py -> _send_handling_auth:
next_request = auth_flow.send(response)
# ...
request = next_request
# Directly loops back to _send_handling_redirects(request)

Because _send_handling_redirects does not know anything about client-level defaults, any new httpx.Request created inside Auth bypasses cookie merging.

If your Auth creates a fresh Request rather than updating or cloning the incoming one, it will go over the wire with no Cookie header.

---

How to ensure cookies are always sent on auth retries

Depending on your auth flow pattern:

Pattern A: Mutate the original request in-place (Recommended)

If you built the request with client.build_request(...) (or used standard client.get/post), request.headers["cookie"] already contains your client cookies. Modify the request in-place rather than allocating a new one:

import httpx

class OnDemandAuth(httpx.Auth):
    async def async_auth_flow(self, request: httpx.Request):
        response = yield request

        if response.status_code == 401:
            # 1. Acquire new credentials / token
            token = await self.fetch_fresh_token()
            request.headers["Authorization"] = f"Bearer {token}"

            # 2. Yield the same request object: cookies are preserved in request.headers
            yield request

Pattern B: Cloning headers when constructing a new Request

If your auth flow needs to re-stream or reconstruct a new Request (for instance, when the body stream was consumed), copy the existing headers across:

class ReplayAuth(httpx.Auth):
    async def async_auth_flow(self, request: httpx.Request):
        response = yield request

        if response.status_code == 401:
            # Construct new request but forward existing headers (including 'cookie')
            new_request = httpx.Request(
                method=request.method,
                url=request.url,
                headers=dict(request.headers),
                content=self.get_fresh_content(),
            )
            yield new_request

Pattern C: Extracting new cookies from intermediate 401 responses

_send_single_request automatically updates client.cookies with any Set-Cookie headers from each intermediate response via self.cookies.extract_cookies(response). If you need those newly set cookies on the subsequent retry request, you can read them directly from the response:

class CookieAwareAuth(httpx.Auth):
    async def async_auth_flow(self, request: httpx.Request):
        response = yield request

        if response.status_code == 401:
            # Merge any Set-Cookie headers received from the challenge into the retry
            for cookie in response.cookies.jar:
                request.headers.append("cookie", f"{cookie.name}={cookie.value}")

            yield request

[Cha-Imaa]

Before retrying, rebuild the header from your shared CookieJar so updated cookies replace stale ones

request.headers.pop("cookie", None)
httpx.Cookies(jar).set_cookie_header(request)