docs: add HTTP mTLS transport examples

[jbeckwith-oai]

Summary

Documents API-key + HTTP mTLS using the SDK's existing transport hooks and adds runnable Node.js, Deno, and Bun examples. Enrollment, activation, certificate requirements, and supported endpoints are linked to the OpenAI Mutual TLS Beta Program.

This intentionally adds no new mtls client option or SDK-owned transport. mTLS remains configured on the runtime HTTP client, so applications retain runtime-native support for passphrases, proxies, custom trust stores, hardware-backed keys, and certificate rotation.

Developer API

Node.js with Undici:

import { readFile } from 'node:fs/promises';
import { Agent, fetch as undiciFetch } from 'undici';
import OpenAI from 'openai';

const dispatcher = new Agent({
  connect: {
    // Leaf certificate first, followed by required intermediates.
    cert: await readFile('/path/to/client-cert-chain.pem'),
    key: await readFile('/path/to/client-key.pem'),
    // Optional, when the transport supports encrypted keys:
    // passphrase: process.env.OPENAI_MTLS_KEY_PASSPHRASE,
  },
});

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'],
  baseURL: 'https://mtls.api.openai.com/v1',
  fetch: undiciFetch,
  fetchOptions: {
    dispatcher,
    redirect: 'manual',
  },
});

try {
  const models = await client.models.list();
} finally {
  await dispatcher.close();
}

For EU Data Residency, use https://mtls-eu.api.openai.com/v1.

The same SDK contract works with runtime-native transports:

• Deno: version-compatible Deno.createHttpClient(...) options passed through a custom fetch;
• Bun: native fetch(..., { tls: { cert, key } });
• Node: Undici Agent({ connect: { cert, key } }) plus matching undici.fetch.

All runnable examples set redirect: 'manual' so a certificate-bearing transport does not automatically follow a redirect to another host.

Files

• Adds a concise mTLS section to README.md.
• Adds examples/mtls/node.mjs, deno.mjs, and bun.mjs.
• Adds examples/mtls/README.md with certificate-chain setup, endpoint selection, encrypted-key guidance for Node, runtime-specific transport cleanup, and Undici's current runtime requirement.
• Adds current Undici 8 only to the examples workspace; the SDK package gains no dependency or peer dependency.

Validation

• ./scripts/build
• ./node_modules/.bin/prettier --check README.md examples/mtls examples/package.json package.json pnpm-lock.yaml
• ./node_modules/.bin/eslint .
• ./node_modules/typescript/bin/tsc -p tsconfig.json
• node --experimental-strip-types scripts/check-node-version-policy.ts
• ./scripts/test --runInBand — 120 suites passed, 1 skipped; 1462 tests passed, 1 skipped
• Real API smoke tests against an enrolled disposable mTLS project:
  • Node.js example with leaf + intermediate chain — success, 184 models returned
  • Bun example with leaf + intermediate chain — success, 184 models returned
  • Deno 1.28.0 legacy option path with an enrolled direct client certificate — success, 184 models returned
  • Deno 2.5.6 modern option path with an enrolled direct client certificate — success, 184 models returned
  • Deno 2.5.6 example with leaf + intermediate chain — success, 184 models returned
  • checked-in Node.js example with Undici 8.8.0 and an enrolled direct client certificate — success, 184 models returned
  • no-certificate control — expected 401 certificate_required

[openai-sdks]

OkTest Summary

✅ 237/237 SDK tests passed in 11.844s for Node SDK PR #2029.

Test results — 42 files

Test	Result	Time
tests/chat-completions-complex-body.test.ts	✅ Passed	285ms
tests/chat-completions-create.test.ts	✅ Passed	334ms
tests/chat-completions-stream.test.ts	✅ Passed	291ms
tests/files-content-binary.test.ts	✅ Passed	200ms
tests/files-create-multipart.test.ts	✅ Passed	276ms
tests/files-list-pagination.test.ts	✅ Passed	205ms
tests/initialize-config.test.ts	✅ Passed	267ms
tests/instance-isolation.test.ts	✅ Passed	215ms
tests/models-list.test.ts	✅ Passed	165ms
tests/responses-background-lifecycle.test.ts	✅ Passed	334ms
tests/responses-body-method-errors.test.ts	✅ Passed	414ms
tests/responses-cancel-timeout.test.ts	✅ Passed	262ms
tests/responses-cancel.test.ts	✅ Passed	253ms
tests/responses-compact-retries.test.ts	✅ Passed	283ms
tests/responses-compact.test.ts	✅ Passed	321ms
tests/responses-create-advanced-stream.test.ts	✅ Passed	170ms
tests/responses-create-advanced.test.ts	✅ Passed	203ms
tests/responses-create-disconnect.test.ts	✅ Passed	1.185s
tests/responses-create-errors.test.ts	✅ Passed	242ms
tests/responses-create-malformed-api-responses.test.ts	✅ Passed	237ms
tests/responses-create-retries.test.ts	✅ Passed	356ms
tests/responses-create-stream-failures.test.ts	✅ Passed	300ms
tests/responses-create-stream-timeout.test.ts	✅ Passed	2.161s
tests/responses-create-stream-wire.test.ts	✅ Passed	2.499s
tests/responses-create-stream.test.ts	✅ Passed	102ms
tests/responses-create-terminal-states.test.ts	✅ Passed	289ms
tests/responses-create-timeout.test.ts	✅ Passed	283ms
tests/responses-create.test.ts	✅ Passed	327ms
tests/responses-delete.test.ts	✅ Passed	289ms
tests/responses-input-items-errors.test.ts	✅ Passed	323ms
tests/responses-input-items-list.test.ts	✅ Passed	189ms
tests/responses-input-items-options.test.ts	✅ Passed	251ms
tests/responses-input-tokens-count-timeout.test.ts	✅ Passed	307ms
tests/responses-input-tokens-count.test.ts	✅ Passed	297ms
tests/responses-malformed-inputs.test.ts	✅ Passed	2.12s
tests/responses-not-found-errors.test.ts	✅ Passed	365ms
tests/responses-parse.test.ts	✅ Passed	247ms
tests/responses-retrieve-retries.test.ts	✅ Passed	309ms
tests/responses-retrieve.test.ts	✅ Passed	289ms
tests/responses-stored-method-errors.test.ts	✅ Passed	842ms
tests/retry-behavior.test.ts	✅ Passed	3.094s
tests/sdk-error-shape.test.ts	✅ Passed	383ms

View OkTest run #30647418261

_{SDK merge (c65375632995) · head (8a44bffb75cf) · base (d6dad64d3189) · OkTest (91635c6a2723)}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0d2b8c11d2

ℹ️ 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".

[HAYDEN-OAI]

Two low-priority copy/paste compatibility issues are noted inline. The mTLS transport approach, endpoint selection, certificate-chain guidance, runtime-specific fetch wiring, manual-redirect protection, and cleanup otherwise look sound.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c2ac20aaf6

ℹ️ 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".