Skip to content

docs(examples): add mTLS and custom TLS configuration example#1280

Open
JakeBx wants to merge 1 commit intoanthropics:mainfrom
JakeBx:docs/mtls-example
Open

docs(examples): add mTLS and custom TLS configuration example#1280
JakeBx wants to merge 1 commit intoanthropics:mainfrom
JakeBx:docs/mtls-example

Conversation

@JakeBx
Copy link
Copy Markdown

@JakeBx JakeBx commented Mar 23, 2026

Closes #1279

What

Adds examples/mtls.py demonstrating how to use the SDK with mTLS client certificate authentication and custom CA bundles.

Why

mTLS is becoming an industry standard for API access in regulated environments. OpenAI recently launched an mTLS beta program for their API, and enterprise users are increasingly expecting the same capability from Anthropic deployments.

Common use cases include:

  • mTLS client certificates for per-user attribution in shared API gateway deployments
  • Custom CA bundles for corporate TLS inspection proxies (Zscaler, Netskope, etc.)

This is a recurring question across the ecosystem:

The underlying SDK already supports this via the http_client parameter, but there is no example or documentation showing the pattern.

How

Uses the existing http_client parameter with DefaultHttpxClient / DefaultAsyncHttpxClient. No SDK code changes required — this is purely documentation of existing capability.

The example builds an ssl.SSLContext with the CA bundle and client certificate, then passes it as verify= to DefaultHttpxClient. This preserves all SDK defaults (connection limits, timeouts, TCP keepalive, proxy detection) while enabling mTLS:

import ssl
from anthropic import Anthropic, DefaultHttpxClient

ctx = ssl.create_default_context()
ctx.load_verify_locations("/path/to/ca-bundle.crt")
ctx.load_cert_chain("/path/to/client.crt", "/path/to/client.key")

client = Anthropic(
    http_client=DefaultHttpxClient(verify=ctx),
)

Covers three scenarios:

  1. mTLS with sync client (Anthropic + DefaultHttpxClient)
  2. mTLS with async client (AsyncAnthropic + DefaultAsyncHttpxClient)
  3. Corporate proxy custom CA bundle (no client cert)

Testing

Verified locally against an nginx mTLS reverse proxy with self-signed certificates. The TLS handshake completes successfully and the SDK correctly processes the upstream response.

@JakeBx JakeBx marked this pull request as ready for review March 23, 2026 02:54
@JakeBx JakeBx requested a review from a team as a code owner March 23, 2026 02:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add example for mTLS / corporate proxy configuration

1 participant