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

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.6}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.5
+Version: 0.3.6
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -187,7 +187,7 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `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. |
+| `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.6}/README.md

@@ -161,7 +161,7 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `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. |
+| `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.6}/codex_backend_sdk/__init__.py

@@ -17,9 +17,9 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.5"
+__version__ = "0.3.6"
 
-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.6}/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.6}/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.6}/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,6 +19,20 @@ 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:
     def __init__(self, client: CodexClient) -> None:

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.6}/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.6}/docs/backend-api.md

@@ -283,7 +283,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 +291,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.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-backend-sdk"
-version = "0.3.5"
+version = "0.3.6"
 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.6}/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")

{codex_backend_sdk-0.3.5 → codex_backend_sdk-0.3.6}/tests/test_realtime_resource.py

@@ -29,14 +29,13 @@ class FakeRealtimeClient(OpenAI):
             refresh_token="refresh-token",
             id_token_raw="id-token",
             account_id="account-id",
-            openai_api_key="sk-test",
+            openai_api_key="realtime-key",
         ))
 
     def _post_raw(self, path, **kwargs):
         self.raw_posts.append((path, kwargs))
         return FakeResponse()
 
-
 def test_realtime_calls_create_posts_plain_sdp_like_official_sdk():
     client = FakeRealtimeClient()
 
@@ -68,13 +67,37 @@ def test_realtime_calls_create_posts_session_as_backend_json():
     assert kwargs["headers"]["Accept"] == "application/sdp"
 
 
-def test_realtime_websocket_helpers_match_codex_agent_plugin_contract():
+def test_realtime_websocket_uses_api_key_exchanged_during_oauth():
     client = FakeRealtimeClient()
 
+    assert client.realtime.websocket_headers(session_id="session-123") == {
+        "Authorization": "Bearer realtime-key",
+        "originator": "codex_cli_rs",
+        "x-session-id": "session-123",
+    }
     assert client.realtime_websocket_url(model="gpt-realtime-1.5") == (
         "wss://api.openai.com/v1/realtime?model=gpt-realtime-1.5"
     )
-    assert client.realtime_websocket_headers(session_id="session-123") == {
-        "Authorization": "Bearer sk-test",
-        "OpenAI-Beta": "realtime=v1",
-    }
+
+
+def test_realtime_websocket_falls_back_to_environment_api_key(monkeypatch):
+    client = FakeRealtimeClient()
+    client._store.openai_api_key = None
+    monkeypatch.setenv("OPENAI_API_KEY", "environment-key")
+
+    assert client.realtime.websocket_headers()["Authorization"] == (
+        "Bearer environment-key"
+    )
+
+
+def test_realtime_websocket_requires_api_key(monkeypatch):
+    client = FakeRealtimeClient()
+    client._store.openai_api_key = None
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    try:
+        client.realtime.websocket_headers()
+    except RuntimeError as exc:
+        assert str(exc) == "Realtime Voice v2 requires an OpenAI API key."
+    else:
+        raise AssertionError("Expected missing Realtime credentials to fail")