Summary

An explicit OPEN-SANDBOX-API-KEY supplied through ConnectionConfig.headers should take precedence over the configured apiKey and its environment fallback — the same contract #2348 established for the JavaScript SDK and #2372 carries to C#. The Kotlin authenticated client violated it:

• HttpClientProvider's AuthenticationInterceptor runs after ExtraHeadersInterceptor (which applies user-supplied headers) and unconditionally replaces the API key header — OkHttp matches header names case-insensitively — so a caller's explicitly supplied credential was always overwritten with the configured key, whatever casing was used.
• With no key configured, the interceptor still attached an empty OPEN-SANDBOX-API-KEY header value to every authenticated request, unlike the JS/C# SDKs which only attach the header when a key exists. (LifecycleMetricsReporter already handled both aspects correctly.)

The fix skips the injection when the request already carries an API key header in any casing (the same guard the neighboring ClientIpInterceptor uses — its comment states the intent that a user-supplied value is preserved), and when the key is blank. Default injection is unchanged when the header is absent and a key is configured.

Testing

• Unit tests: 3 new behavioral regression cases fail on the base commit (explicit canonical-casing header, explicit lowercase header, and no header when unconfigured) and pass after the fix, plus one control case for default injection. New ApiKeyHeaderTest uses MockWebServer end-to-end against authenticatedClient, following the existing ClientIpTest pattern.
• ./gradlew spotlessCheck :sandbox:test :code-interpreter:test — 531 tests, 0 failures (JDK 8 toolchain provisioned locally for :code-interpreter).
• pnpm docs:build was not run (no pnpm available locally); the docs change is one prose paragraph in docs/sdks/kotlin.md.
• Live sandbox / cross-language integration tests were not run.

Breaking Changes

• None: an explicitly supplied header is now honored per HTTP's case-insensitive header semantics; the only other behavior change is that authenticated requests no longer carry an empty API key header when no key is configured.

Checklist

• Clearly described motivation
• Added/updated docs (a short note in docs/sdks/kotlin.md, mirroring the JavaScript/C# SDK notes)
• Added regression tests
• Security impact considered: preserves the caller's selected credential instead of silently substituting it; no new credential exposure
• Backward compatibility considered

Prepared with AI assistance. Checked the open PR queue for in-flight Kotlin header-precedence work before submitting.