feat(auth): support x-api-key for proxy API key auth

[SSinist3r]

Summary

Supports x-api-key alongside Bearer tokens for proxy-facing API key authentication so compatible clients and reverse proxies can authenticate without header rewrites. Authorization remains the preferred source when both are present, with x-api-key used as a fallback only when needed.

Type of change

• feat: — new user-facing feature or capability
• fix: — bug fix (no behavior change beyond the bug)
• refactor: — internal refactor (no behavior change, no API change)
• docs: — documentation only
• chore: / ci: / build: — tooling, CI, packaging
• test: — test-only change
• Breaking change (also append ! after the type, e.g. feat!: or include BREAKING CHANGE: footer)

Linked issue:

OpenSpec

• This PR includes / updates an OpenSpec change
• Not applicable — bug fix that matches the existing spec
• Not applicable — docs / CI / chore only
• This PR touches a codex-faithful path (image pipeline, request/response
  shape, SSE framing, OAuth flow) and preserves upstream-equivalent behavior

Change directory: openspec/changes/support-x-api-key-auth/

Changes

• Accepts x-api-key for proxy API key validation and self-service usage lookup.
• Preserves Bearer-first precedence, with fallback to x-api-key when Authorization is absent, malformed, or invalid.
• Keeps ChatGPT caller-identity flows Bearer-only and strips inbound x-api-key from proxied requests.
• Adds regression coverage for auth precedence, websocket auth, usage lookup, and header filtering.

Test plan

# uv run pytest tests/unit/test_hot_path_caches.py -q
# uv run pytest tests/unit/test_proxy_api_websocket_auth.py -q
# uv run pytest tests/unit/test_proxy_utils.py -q
# uv run pytest tests/integration/test_auth_middleware.py -q
# uv run pytest tests/integration/test_v1_usage.py -q

Screenshots / output (optional)

Example behavior:

• Authorization: Bearer + x-api-key: now authenticates successfully
• GET /v1/usage accepts a valid x-api-key
• x-api-key is ignored for Bearer-only caller identity paths

Checklist

• Title is in Conventional Commits format (()?: ).
• Linked the related issue / discussion above — Pi custom provider (openai-codex-responses) needs x-api-key support to use codex-lb without header rewrites.
• Added or updated tests covering the change.
• Ran uv run pre-commit run local-ci --hook-stage manual --all-files or the relevant make subset locally.
• If touching specs: openspec validate --specs passes and /opsx:verify is clean.
• CHANGELOG is not edited by hand (release-please handles it).

[Soju06]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. More of your lovely PRs please.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Soju06]

Hermes owner-review blocker: x-api-key auth is lost on HTTP bridge owner-forward paths.

Evidence:

• app/modules/proxy/service.py:599-613 saves only the inbound Authorization as proxy_api_authorization, then passes filter_inbound_headers(headers) onward.
• app/core/clients/proxy.py:68-70 now strips x-api-key from filter_inbound_headers().
• app/modules/proxy/service.py:1793 / :14757-14764 re-add only Authorization before forwarding to the owner replica.
• The owner handler re-authenticates before streaming: app/modules/proxy/api.py:585 -> _validate_internal_bridge_api_key(), which needs either Authorization or x-api-key after this PR (app/core/auth/dependencies.py:74-83).

Result: when api_key_auth_enabled=true and HTTP bridge owner-forwarding happens, requests authenticated with only x-api-key reach the owner without any API key and fail 401. The documented fallback case Authorization: Bearer invalid + valid x-api-key also fails after forwarding because the invalid Authorization is the only auth header restored.

Please preserve the validated proxy API key credential for internal owner-forward re-auth (or otherwise make internal bridge auth use the already-validated reservation/context safely) and add a regression test for owner-forward with x-api-key-only and invalid-Bearer+valid-x-api-key.

[Komzpa]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Swish!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".