Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

fix(sdk-js): honor API key headers regardless of casing

Claire-ovo2a5638eaa739
diff --git a/docs/sdks/javascript.md b/docs/sdks/javascript.md
index 58b8d196a..ce8cd66f3 100644
--- a/docs/sdks/javascript.md
+++ b/docs/sdks/javascript.md
@@ -475,6 +475,8 @@ await sandbox.patchMetadata({ project: "demo", "obsolete-key": null });
The `ConnectionConfig` class manages API server connection settings.
+An explicit `OPEN-SANDBOX-API-KEY` in `headers` takes precedence over `apiKey` and its environment fallback, regardless of header-name casing. This also applies to the low-level lifecycle and diagnostic clients.
+
::: info Runtime Notes
- In browsers, the SDK uses the global `fetch` implementation.
- `requestTimeoutSeconds` bounds the wait for a response: it stops applying once the response headers arrive (streaming responses are not cut off). It never caps a healthy file upload body, which can legitimately take longer than the timeout; on Node.js a stalled upload, or an upload that gets no response headers within the timeout once the body has been sent, is aborted instead of hanging (the Go SDK's `ResponseHeaderTimeout` contract).
diff --git a/sdks/sandbox/javascript/src/config/connection.ts b/sdks/sandbox/javascript/src/config/connection.ts
index d4be97ad3..2b4e0dc57 100644
--- a/sdks/sandbox/javascript/src/config/connection.ts
+++ b/sdks/sandbox/javascript/src/config/connection.ts
@@ -434,7 +434,7 @@ export class ConnectionConfig {
const headers: Record<string, string> = { ...(opts.headers ?? {}) };
// Attach API key via header unless the user already provided one.
- if (this.apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {
+ if (this.apiKey && !Object.keys(headers).some((name) => name.toLowerCase() === "open-sandbox-api-key")) {
headers["OPEN-SANDBOX-API-KEY"] = this.apiKey;
}
// Best-effort user-agent (Node only).
diff --git a/sdks/sandbox/javascript/src/openapi/lifecycleClient.ts b/sdks/sandbox/javascript/src/openapi/lifecycleClient.ts
index af2752e7b..09407e0a2 100644
--- a/sdks/sandbox/javascript/src/openapi/lifecycleClient.ts
+++ b/sdks/sandbox/javascript/src/openapi/lifecycleClient.ts
@@ -65,7 +65,7 @@ export function createLifecycleApiClient<Paths extends object>(
...(opts.headers ?? {}),
};
- if (apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {
+ if (apiKey && !Object.keys(headers).some((name) => name.toLowerCase() === "open-sandbox-api-key")) {
headers["OPEN-SANDBOX-API-KEY"] = apiKey;
}
diff --git a/sdks/sandbox/javascript/tests/connection.header-precedence.test.mjs b/sdks/sandbox/javascript/tests/connection.header-precedence.test.mjs
new file mode 100644
index 000000000..83e3f0cb9
--- /dev/null
+++ b/sdks/sandbox/javascript/tests/connection.header-precedence.test.mjs
@@ -0,0 +1,60 @@
+// Copyright 2026 The OpenSandbox Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ConnectionConfig } from "../dist/index.js";
+import { createLifecycleClient, createDiagnosticClient } from "../dist/internal.js";
+
+for (const headerName of ["OPEN-SANDBOX-API-KEY", "open-sandbox-api-key", "Open-Sandbox-Api-Key"]) {
+ test(`ConnectionConfig preserves an explicit ${headerName}`, () => {
+ const headers = { [headerName]: "explicit-key", "X-Custom": "kept" };
+ const config = new ConnectionConfig({ apiKey: "fallback-key", headers });
+ for (const candidate of [config, config.withCreateMetricsDisabled()]) {
+ assert.equal(new Headers(candidate.headers).get("open-sandbox-api-key"), "explicit-key");
+ assert.equal(new Headers(candidate.headers).get("x-custom"), "kept");
+ }
+ assert.deepEqual(headers, { [headerName]: "explicit-key", "X-Custom": "kept" });
+ });
+
+ for (const [name, factory, path] of [
+ ["lifecycle", createLifecycleClient, "/sandboxes"],
+ ["diagnostic", createDiagnosticClient, "/diagnostics/context"],
+ ]) {
+ test(`${name} sends only the explicit ${headerName}`, async () => {
+ const requests = [];
+ const client = factory({
+ apiKey: "fallback-key",
+ headers: { [headerName]: "explicit-key" },
+ fetch: async (request) => {
+ requests.push(request);
+ return Response.json({});
+ },
+ });
+ await client.GET(path);
+ assert.equal(requests.length, 1);
+ assert.equal(requests[0].headers.get("open-sandbox-api-key"), "explicit-key");
+ });
+ }
+}
+
+test("missing API key header still uses the configured fallback", async () => {
+ const config = new ConnectionConfig({ apiKey: "fallback-key" });
+ assert.equal(new Headers(config.headers).get("open-sandbox-api-key"), "fallback-key");
+ const client = createLifecycleClient({
+ apiKey: "fallback-key",
+ fetch: async (request) => {
+ assert.equal(request.headers.get("open-sandbox-api-key"), "fallback-key");
+ return Response.json({});
+ },
+ });
+ await client.GET("/sandboxes");
+});