codex-backend-sdk 0.3.5__tar.gz → 0.3.7__tar.gz

codex_backend_sdk-0.3.7/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.7] - 2026-07-17
+
+### Added
+- Added typed Realtime call results through `RealtimeCallResponse.answer_sdp` and `RealtimeCallResponse.call_id`.
+- Added Codex AVAS session payload support, including automatic removal of the server-generated session `id` and the required `quicksilver` query parameters.
+
+### Documentation
+- Documented that the ChatGPT-authenticated Codex WebRTC route is experimental and rollout-dependent, while the public Realtime WebSocket route still requires a developer API key.
+
+### Tests
+- Added coverage for SDP response parsing, call ID validation, AVAS payload construction, and invalid session payloads.
+
+## [0.3.6] - 2026-07-11
+
+### Added
+- Added Voice v2 WebSocket headers through `client.realtime.websocket_headers(...)`, using the API key stored by OAuth when available or `OPENAI_API_KEY` as a fallback.
+- Added `authenticate(force=True)` for explicit interactive reauthentication.
+
+### Changed
+- ChatGPT OAuth now attempts the same optional ID-token-to-API-key exchange as Codex CLI and persists the result in the official `OPENAI_API_KEY` auth field.
+- Removed the legacy `request_api_key` authentication option; API-key acquisition is now an internal OAuth concern and never prevents regular Codex login.
+
+### Tests
+- Added coverage for forced authentication and Realtime credential selection/error behavior.
+
+## [0.3.5] - 2026-05-18
+
+### Fixed
+- Preserved `usage` on `client.responses.compact(...)` results so `CompactedResponse` exposes backend token accounting.
+
+### Tests
+- Added coverage to verify compact responses retain `input_tokens`, `output_tokens`, and `total_tokens`.
+
+## [0.3.4] - 2026-05-15
+
+### Added
+- Added `authenticate(interactive=False)` to allow non-interactive credential checks without triggering the browser OAuth flow.
+- Added `client.authenticated` for simple auth-state introspection.
+- Added `client.account_info()` to expose safe non-secret account metadata (`authenticated`, `account_id`, `email`, `plan_type`).
+
+### Documentation
+- Documented the non-interactive authentication helpers in `README.md`.

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.5
+Version: 0.3.7
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -186,8 +186,8 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `POST /backend-api/codex/responses/compact` | `client.responses.compact(...)` | Codex-specific helper for encrypted context compaction. |
 | `POST /backend-api/codex/memories/trace_summarize` | `client.codex.memories.trace_summarize(...)` | Raw Codex memory trace summarization helper. |
 | `GET /backend-api/codex/models` | `client.models.list()` / `client.models.retrieve(...)` | OpenAI-shaped model objects with Codex metadata preserved as extra fields. |
-| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | OpenAI-shaped SDP call creation for realtime sessions. |
-| `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime_websocket_headers(...)` | Helper surface used by codex-agent's realtime plugin. |
+| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | Experimental SDP call creation. The protocol is implemented by Codex, but ChatGPT routing is rollout-dependent and may return `404 Not Found`. |
+| `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime.websocket_headers(...)` | Voice v2 helpers; requires a Realtime API key obtained during OAuth or supplied by the auth store. |
 | `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `text-embedding-3-small`. |
 | `POST /v1/audio/transcriptions` | `client.audio.transcriptions.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `gpt-4o-mini-transcribe`. |
 | `GET /backend-api/wham/usage` | `client.codex.usage()` | Codex/ChatGPT quota and rate-limit status. |
@@ -343,17 +343,18 @@ answer = client.realtime.calls.create(
 print(answer.text)
 ```
 
-For WebSocket-based plugins such as `codex-agent`, the client also exposes small
-helpers that reuse the OpenAI API key stored by the Codex OAuth flow:
+For WebSocket-based plugins such as `codex-agent`, the client also exposes the
+Voice v2 connection details:
 
 ```python
 url = client.realtime_websocket_url(model="gpt-realtime-1.5")
-headers = client.realtime_websocket_headers(session_id="voice-session")
+headers = client.realtime.websocket_headers(session_id="voice-session")
 ```
 
-`realtime_websocket_headers(...)` requires `~/.codex/auth.json` to contain
-`openai_api_key`. The default `authenticate(request_api_key=True)` flow stores
-that key when available.
+During interactive ChatGPT OAuth login, the SDK exchanges the fresh ID token for
+the temporary API key required by Realtime and stores it with the other local
+credentials. Existing credentials created by older SDK versions may require one
+forced interactive login before these headers are available.
 
 For non-interactive checks, you can avoid triggering a browser login flow:
 

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/README.md

@@ -160,8 +160,8 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `POST /backend-api/codex/responses/compact` | `client.responses.compact(...)` | Codex-specific helper for encrypted context compaction. |
 | `POST /backend-api/codex/memories/trace_summarize` | `client.codex.memories.trace_summarize(...)` | Raw Codex memory trace summarization helper. |
 | `GET /backend-api/codex/models` | `client.models.list()` / `client.models.retrieve(...)` | OpenAI-shaped model objects with Codex metadata preserved as extra fields. |
-| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | OpenAI-shaped SDP call creation for realtime sessions. |
-| `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime_websocket_headers(...)` | Helper surface used by codex-agent's realtime plugin. |
+| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | Experimental SDP call creation. The protocol is implemented by Codex, but ChatGPT routing is rollout-dependent and may return `404 Not Found`. |
+| `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime.websocket_headers(...)` | Voice v2 helpers; requires a Realtime API key obtained during OAuth or supplied by the auth store. |
 | `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `text-embedding-3-small`. |
 | `POST /v1/audio/transcriptions` | `client.audio.transcriptions.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `gpt-4o-mini-transcribe`. |
 | `GET /backend-api/wham/usage` | `client.codex.usage()` | Codex/ChatGPT quota and rate-limit status. |
@@ -317,17 +317,18 @@ answer = client.realtime.calls.create(
 print(answer.text)
 ```
 
-For WebSocket-based plugins such as `codex-agent`, the client also exposes small
-helpers that reuse the OpenAI API key stored by the Codex OAuth flow:
+For WebSocket-based plugins such as `codex-agent`, the client also exposes the
+Voice v2 connection details:
 
 ```python
 url = client.realtime_websocket_url(model="gpt-realtime-1.5")
-headers = client.realtime_websocket_headers(session_id="voice-session")
+headers = client.realtime.websocket_headers(session_id="voice-session")
 ```
 
-`realtime_websocket_headers(...)` requires `~/.codex/auth.json` to contain
-`openai_api_key`. The default `authenticate(request_api_key=True)` flow stores
-that key when available.
+During interactive ChatGPT OAuth login, the SDK exchanges the fresh ID token for
+the temporary API key required by Realtime and stores it with the other local
+credentials. Existing credentials created by older SDK versions may require one
+forced interactive login before these headers are available.
 
 For non-interactive checks, you can avoid triggering a browser login flow:
 

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/codex_backend_sdk/__init__.py

@@ -17,9 +17,9 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.5"
+__version__ = "0.3.7"
 
-from .oauth import run_oauth_flow, refresh_access_token, obtain_api_key
+from .oauth import run_oauth_flow, refresh_access_token
 from .storage import load_tokens, save_tokens, TokenStore
 from .codex_client import (
     CodexBackendUnsupportedParameterError,
@@ -83,7 +83,6 @@ __all__ = [
     "image_b64",
     "run_oauth_flow",
     "refresh_access_token",
-    "obtain_api_key",
     "load_tokens",
     "save_tokens",
     "TokenStore",

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/codex_backend_sdk/_client.py

@@ -65,28 +65,38 @@ class CodexClient:
     def authenticate(
         self,
         *,
-        request_api_key: bool = True,
         interactive: bool = True,
+        force: bool = False,
     ) -> "CodexClient":
-        from .oauth import refresh_access_token, run_oauth_flow
+        from .oauth import obtain_api_key, refresh_access_token, run_oauth_flow
 
         def refresh(store: TokenStore) -> Optional[TokenStore]:
             try:
                 data = refresh_access_token(store.refresh_token)
+                id_token = data.get("id_token", store.id_token_raw)
+                api_key = store.openai_api_key
+                if not api_key and data.get("id_token"):
+                    try:
+                        api_key = obtain_api_key(id_token)
+                    except Exception:
+                        pass
                 refreshed = TokenStore.from_exchange(
                     access_token=data.get("access_token", store.access_token),
                     refresh_token=data.get("refresh_token", store.refresh_token),
-                    id_token=data.get("id_token", store.id_token_raw),
-                    api_key=store.openai_api_key,
+                    id_token=id_token,
+                    openai_api_key=api_key,
                 )
                 save_tokens(refreshed)
                 return refreshed
             except Exception:
                 return None
 
-        store = load_tokens()
+        if force and not interactive:
+            raise ValueError("Forced authentication requires interactive=True.")
+
+        store = None if force else load_tokens()
         if store is not None:
-            if token_needs_refresh(store) and store.refresh_token:
+            if (token_needs_refresh(store) or not store.openai_api_key) and store.refresh_token:
                 store = refresh(store) or store
             if not token_needs_refresh(store) or self._probe_auth(store):
                 self._set_store(store)
@@ -95,7 +105,7 @@ class CodexClient:
         if not interactive:
             raise RuntimeError("No usable stored Codex credentials; interactive login required.")
 
-        self._set_store(run_oauth_flow(request_api_key=request_api_key))
+        self._set_store(run_oauth_flow())
         return self
 
     @property
@@ -312,18 +322,5 @@ class CodexClient:
             raise ValueError(f"Expected a non-empty value for `model` but received {model!r}")
         return "wss://api.openai.com/v1/realtime?" + urllib.parse.urlencode({"model": model})
 
-    def realtime_websocket_headers(self, *, session_id: Optional[str] = None) -> dict[str, str]:
-        """Return headers for an OpenAI Realtime WebSocket connection."""
-        self._ensure_auth()
-        if self._store is None or not self._store.openai_api_key:
-            raise RuntimeError(
-                "Realtime WebSocket requires an OpenAI API key. "
-                "Call authenticate(request_api_key=True) to persist one."
-            )
-        return {
-            "Authorization": f"Bearer {self._store.openai_api_key}",
-            "OpenAI-Beta": "realtime=v1",
-        }
-
 
 OpenAI = CodexClient

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/codex_backend_sdk/_models.py

@@ -304,4 +304,30 @@ class BinaryResponseContent:
 
 
 class RealtimeCallResponse(BinaryResponseContent):
-    """Binary SDP response returned by ``client.realtime.calls.create``."""
+    """SDP answer and call identifier returned by Realtime call creation."""
+
+    @property
+    def answer_sdp(self) -> str:
+        return self.text
+
+    @property
+    def call_id(self) -> str:
+        location = self.response.headers.get("Location")
+        if not location:
+            raise RuntimeError("Realtime call response is missing the Location header.")
+        path = location.split("?", 1)[0].rstrip("/")
+        call_id = path.rsplit("/", 1)[-1]
+        if call_id.startswith("rtc_") or _is_uuid(call_id):
+            return call_id
+        raise RuntimeError(
+            f"Realtime call Location does not contain a valid call id: {location}"
+        )
+
+
+def _is_uuid(value: str) -> bool:
+    if len(value) != 36:
+        return False
+    return all(
+        char == "-" if index in {8, 13, 18, 23} else char in "0123456789abcdefABCDEF"
+        for index, char in enumerate(value)
+    )

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/codex_backend_sdk/oauth.py

@@ -150,48 +150,22 @@ def _exchange_code(code: str, pkce: PkceCodes) -> dict:
     return resp.json()
 
 
-def obtain_api_key(id_token: str, access_token: Optional[str] = None) -> Optional[str]:
-    """
-    Exchange an id_token (or access_token fallback) for an OpenAI API key.
-    Returns the API key string, or None on failure.
-
-    Some accounts (personal API Platform orgs) don't embed organization_id in
-    the id_token. We first try with the id_token; if that fails with an org
-    error, we retry using the access_token (already scoped to api.openai.com/v1).
-    """
-    def _exchange(subject: str, token_type: str) -> Optional[str]:
-        resp = requests.post(
-            f"{ISSUER}/oauth/token",
-            headers={"Content-Type": "application/x-www-form-urlencoded"},
-            data={
-                "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
-                "client_id": CLIENT_ID,
-                "requested_token": "openai-api-key",
-                "subject_token": subject,
-                "subject_token_type": token_type,
-            },
-            timeout=30,
-        )
-        if resp.ok:
-            return resp.json().get("access_token")
-        short_type = token_type.split(":")[-1]
-        print(f"[auth] {short_type} exchange → {resp.status_code}: {resp.text}")
-        return None
-
-    try:
-        key = _exchange(id_token, "urn:ietf:params:oauth:token-type:id_token")
-        if key:
-            return key
-
-        if access_token:
-            print("[auth] retrying with access_token…")
-            key = _exchange(access_token, "urn:ietf:params:oauth:token-type:access_token")
-            if key:
-                return key
-
-    except Exception as exc:
-        print(f"[auth] API key exchange error: {exc}")
-    return None
+def obtain_api_key(id_token: str) -> str:
+    """Exchange a fresh ChatGPT ID token for the API key used by Realtime."""
+    resp = requests.post(
+        f"{ISSUER}/oauth/token",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        data={
+            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+            "client_id": CLIENT_ID,
+            "requested_token": "openai-api-key",
+            "subject_token": id_token,
+            "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
+        },
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.json()["access_token"]
 
 
 def refresh_access_token(refresh_token: str) -> dict:
@@ -217,7 +191,6 @@ def refresh_access_token(refresh_token: str) -> dict:
 def run_oauth_flow(
     *,
     open_browser: bool = True,
-    request_api_key: bool = True,
     persist: bool = True,
     workspace_id: Optional[str] = None,
     scopes: Optional[str] = None,
@@ -226,8 +199,7 @@ def run_oauth_flow(
     Run the full OAuth authorization-code + PKCE flow.
 
     Opens the browser (unless open_browser=False), waits for the callback,
-    exchanges the code for tokens, optionally fetches an API key,
-    and saves everything to ~/.codex/auth.json.
+    exchanges the code for OAuth tokens and saves them to ~/.codex/auth.json.
 
     Returns a TokenStore with all credentials.
     """
@@ -278,18 +250,16 @@ def run_oauth_flow(
     refresh_token = raw["refresh_token"]
     id_token = raw["id_token"]
 
-    api_key: Optional[str] = None
-    if request_api_key:
-        print("[auth] Exchanging for OpenAI API key …")
-        api_key = obtain_api_key(id_token, access_token)
-        if api_key:
-            print(f"[auth] API key obtained: {api_key[:8]}…")
+    try:
+        openai_api_key = obtain_api_key(id_token)
+    except requests.HTTPError:
+        openai_api_key = None
 
     store = TokenStore.from_exchange(
         access_token=access_token,
         refresh_token=refresh_token,
         id_token=id_token,
-        api_key=api_key,
+        openai_api_key=openai_api_key,
     )
 
     if persist:

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/codex_backend_sdk/resources/realtime.py

@@ -1,6 +1,8 @@
 """Realtime resources."""
 
 from __future__ import annotations
+
+import os
 from typing import Any, Optional, TYPE_CHECKING
 
 from .._models import RealtimeCallResponse
@@ -17,8 +19,28 @@ class Realtime:
         self._client = client
         self.calls = RealtimeCalls(client)
 
+    def websocket_headers(self, *, session_id: Optional[str] = None) -> dict[str, str]:
+        """Return Voice v2 headers backed by an available Realtime API key."""
+        store = self._client._store
+        api_key = (store.openai_api_key if store else None) or os.environ.get("OPENAI_API_KEY")
+        if not api_key:
+            raise RuntimeError("Realtime Voice v2 requires an OpenAI API key.")
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "originator": "codex_cli_rs",
+        }
+        if session_id:
+            headers["x-session-id"] = session_id
+        return headers
+
 
 class RealtimeCalls:
+    """Experimental Codex WebRTC call creation.
+
+    Availability depends on the Realtime call route enabled for the authenticated
+    ChatGPT account. A correctly authenticated request may still return 404 while
+    the backend is not rolled out.
+    """
     def __init__(self, client: CodexClient) -> None:
         self._client = client
 
@@ -49,15 +71,23 @@ class RealtimeCalls:
             )
             return RealtimeCallResponse(response)
 
+        session_payload = _jsonable(session)
+        if not isinstance(session_payload, dict):
+            raise TypeError("Expected `session` to serialize to a JSON object.")
+        session_payload.pop("id", None)
+        body = {
+            "sdp": sdp,
+            "session": session_payload,
+            **(_jsonable(extra_body) if extra_body else {}),
+        }
+        query = {"intent": "quicksilver", "architecture": "avas"}
+        if extra_query:
+            query.update(extra_query)
         response = self._client._post_raw(
             "/realtime/calls",
-            body={
-                "sdp": sdp,
-                "session": _jsonable(session),
-                **(_jsonable(extra_body) if extra_body else {}),
-            },
+            body=body,
             headers={"Accept": "application/sdp", **(extra_headers or {})},
-            params=extra_query,
+            params=query,
             timeout=timeout,
         )
         return RealtimeCallResponse(response)

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/codex_backend_sdk/storage.py

@@ -66,7 +66,7 @@ class TokenStore:
         access_token: str,
         refresh_token: str,
         id_token: str,
-        api_key: Optional[str] = None,
+        openai_api_key: Optional[str] = None,
     ) -> "TokenStore":
         claims = _extract_openai_claims(id_token)
         access_claims = _extract_openai_claims(access_token)
@@ -76,7 +76,7 @@ class TokenStore:
             refresh_token=refresh_token,
             id_token_raw=id_token,
             account_id=claims.get("chatgpt_account_id"),
-            openai_api_key=api_key,
+            openai_api_key=openai_api_key,
             last_refresh=datetime.now(timezone.utc).isoformat(),
             email=_decode_jwt_payload(id_token).get("email"),
             plan_type=access_claims.get("chatgpt_plan_type"),
@@ -119,7 +119,7 @@ def save_tokens(store: TokenStore) -> None:
 
     payload = {
         "auth_mode": "chatgpt",
-        "openai_api_key": store.openai_api_key,
+        "OPENAI_API_KEY": store.openai_api_key,
         "tokens": {
             "access_token": store.access_token,
             "refresh_token": store.refresh_token,
@@ -159,7 +159,7 @@ def load_tokens() -> Optional[TokenStore]:
         refresh_token=refresh_token,
         id_token_raw=id_token,
         account_id=tokens.get("account_id"),
-        openai_api_key=data.get("openai_api_key"),
+        openai_api_key=data.get("OPENAI_API_KEY") or data.get("openai_api_key"),
         last_refresh=data.get("last_refresh"),
         email=_decode_jwt_payload(id_token).get("email"),
         plan_type=_extract_openai_claims(access_token).get("chatgpt_plan_type"),

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/docs/backend-api.md

@@ -264,14 +264,21 @@ Realtime audio/video call initiation.
 
 **SDK method**: `client.realtime.calls.create(...)`
 
-**Status**: Supported. The SDK follows the official OpenAI SDK shape:
+**Status**: Experimental and rollout-dependent. The SDK follows the Codex
+client protocol:
 
 - plain SDP offer: `client.realtime.calls.create(sdp=offer_sdp)`
-- SDP offer plus session payload:
+- AVAS SDP offer plus session payload:
   `client.realtime.calls.create(sdp=offer_sdp, session={...})`
 
-The response is returned as binary SDP content with `.content`, `.text`,
-`.read()`, `.iter_bytes()`, and `.write_to_file(...)` helpers.
+The OAuth-authenticated ChatGPT route is not enabled for every account and may
+return `404 Not Found` until Codex supplies an experimental WebRTC call base URL.
+This is distinct from the public Realtime WebSocket route, which currently
+requires a developer API key.
+
+The response exposes `.answer_sdp` and `.call_id`, while preserving the binary
+helpers `.content`, `.text`, `.read()`, `.iter_bytes()`, and
+`.write_to_file(...)`.
 
 ---
 
@@ -283,7 +290,7 @@ sharing the Codex OAuth/token store.
 **SDK methods**:
 
 - `client.realtime_websocket_url(model="gpt-realtime-1.5")`
-- `client.realtime_websocket_headers(session_id="...")`
+- `client.realtime.websocket_headers(session_id="...")`
 
 The URL helper returns:
 
@@ -291,10 +298,11 @@ The URL helper returns:
 wss://api.openai.com/v1/realtime?model=...
 ```
 
-The headers helper returns `Authorization: Bearer <openai_api_key>` and
-`OpenAI-Beta: realtime=v1`. It requires the Codex auth store to contain
-`openai_api_key`; the default `authenticate(request_api_key=True)` flow requests
-and persists it.
+The headers helper returns `Authorization: Bearer <openai_api_key>`, the Codex
+originator, and the optional session id. Interactive ChatGPT OAuth attempts to
+exchange its fresh ID token for this Realtime API key and persists it when the
+account is entitled to one. If that exchange is unavailable, regular Codex OAuth
+continues to work but Voice v2 requires a separately provisioned API key.
 
 ---
 

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-backend-sdk"
-version = "0.3.5"
+version = "0.3.7"
 description = "Unofficial Python SDK for the ChatGPT Codex backend API"
 readme = "README.md"
 license = { text = "MIT" }

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.7}/tests/test_account_info.py

@@ -66,3 +66,22 @@ def test_authenticate_non_interactive_without_tokens_raises(monkeypatch):
         assert "interactive login required" in str(exc)
     else:
         raise AssertionError("Expected RuntimeError")
+
+
+def test_authenticate_force_runs_interactive_flow(monkeypatch):
+    expected = _store()
+    monkeypatch.setattr("codex_backend_sdk._client.load_tokens", lambda: _store())
+    monkeypatch.setattr("codex_backend_sdk.oauth.run_oauth_flow", lambda: expected)
+
+    client = CodexClient().authenticate(force=True)
+
+    assert client._store is expected
+
+
+def test_authenticate_force_requires_interactive_mode():
+    try:
+        CodexClient().authenticate(force=True, interactive=False)
+    except ValueError as exc:
+        assert "interactive=True" in str(exc)
+    else:
+        raise AssertionError("Expected ValueError")