Anthropic SDK Setup Guide
Route the Anthropic SDK through Lucairn in 2 minutes
No Anthropic-specific setup page existed before — config was scattered across /integration. This is the canonical guide for the Anthropic SDK (Python + TypeScript) against the Lucairn gateway.
Export the two keys
You need a Lucairn key (lcr_live_*) for rate limiting and audit identity, and your Anthropic key (sk-ant-*) which Lucairn forwards upstream per request — BYOK, never stored. If you don't have a Lucairn key yet, sign up at /account/signup.
Install the Anthropic SDK
Use the official Anthropic SDK — Python (pip install anthropic) or TypeScript (npm install @anthropic-ai/sdk). No Lucairn SDK to install. The Anthropic SDK targets the Lucairn gateway via base_url.
Point base_url at Lucairn and run the example
Set api_key to your Lucairn key (the SDK sends it as x-api-key, which Lucairn recognises by the lcr_live_ prefix), set base_url to https://gateway.lucairn.eu, and pass your Anthropic key in the X-Upstream-Key header. Lucairn intercepts, sanitises, isolates, signs, then forwards to Anthropic.
# Two keys: your Lucairn key (rate-limit + audit identity)
# and your Anthropic key (BYOK — forwarded upstream per request).
export LUCAIRN_API_KEY="lcr_live_..."
export ANTHROPIC_API_KEY="sk-ant-..."# Python
pip install anthropic
# TypeScript
npm install @anthropic-ai/sdkimport os
import anthropic
client = anthropic.Anthropic(
api_key=os.environ["LUCAIRN_API_KEY"], # Lucairn key — sent as x-api-key
base_url="https://gateway.lucairn.eu", # Lucairn Gateway
default_headers={
"X-Upstream-Key": os.environ["ANTHROPIC_API_KEY"], # your Anthropic key (BYOK)
},
)
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{
"role": "user",
"content": (
"Bitte fasse den Fall zusammen: "
"Patientin Anna Schmidt, geb. 14.03.1978, "
"IBAN DE89 3704 0044 0532 0130 00, "
"wurde am 02.05.2026 in der Charite vorgestellt."
),
}],
)
print(response.content[0].text)
print(response.metadata["dsa_compliance"]["veil_summary_url"])import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.LUCAIRN_API_KEY!, // Lucairn key — sent as x-api-key
baseURL: "https://gateway.lucairn.eu", // Lucairn Gateway
defaultHeaders: {
"X-Upstream-Key": process.env.ANTHROPIC_API_KEY!, // your Anthropic key (BYOK)
},
});
const response = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [{
role: "user",
content:
"Bitte fasse den Fall zusammen: Patientin Anna Schmidt, " +
"geb. 14.03.1978, IBAN DE89 3704 0044 0532 0130 00, " +
"wurde am 02.05.2026 in der Charite vorgestellt.",
}],
});
console.log(response.content[0]);
// @ts-expect-error metadata.dsa_compliance is a Lucairn extension
console.log(response.metadata?.dsa_compliance?.veil_summary_url);curl https://gateway.lucairn.eu/v1/messages \
-H "x-api-key: $LUCAIRN_API_KEY" \
-H "X-Upstream-Key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 256,
"messages": [{
"role": "user",
"content": "Patientin Anna Schmidt, IBAN DE89 3704 0044 0532 0130 00 — bitte zusammenfassen."
}]
}'How it works
The Anthropic SDK's api_key field is sent as the x-api-key header. Lucairn's gateway recognises lcr_live_* prefixes there as the customer key, and reads your real Anthropic key from X-Upstream-Key. Source: services/gateway/internal/api/anthropic_handler.go + upstream_key.go.
Every message — system prompt and every conversation turn — is scanned for PII (names, emails, addresses, IBANs, German medical terms) before it reaches Anthropic. PII is replaced with safe placeholders.
Anthropic only ever sees sanitised text. Your real Anthropic key is forwarded per request and never stored, logged, or cached on the gateway.
Developer-tier responses contain placeholders ([PERSON_1], [IBAN_1], …) so your code never receives raw PII. Pro and Enterprise tiers can enable automatic re-linking back to the original values inside your environment.
Every response carries a metadata.dsa_compliance block — request_id, veil_certificate_url, veil_summary_url, redaction_count, sanitizer_layers, latency_ms — your cryptographic proof of what was sanitised. Open the veil_summary_url to inspect the receipt.
Streaming (stream:true) is gated on the gateway by STREAMING_ENABLED. On the hosted gateway.lucairn.eu it is OFF today; on a self-hosted Lucairn you can enable it. When enabled, per-chunk relinking runs as each SSE chunk leaves the gateway.
Capability matrix
Before you paste this into a production app, check what the Anthropic-compatible proxy actually covers today. Under-promise, over-deliver — we list the real gaps.
| Capability | Works today | Notes |
|---|---|---|
| Non-streaming messages (stream:false) | ✓ | Full PII sanitisation across system prompt + every turn + signed Lucairn Certificate per request. |
| System prompts | ✓ | System message is sanitised end-to-end alongside the user turns. Hard-identifier patterns in the system prompt are rejected with HTTP 400 — move PII into user messages. |
| Multi-turn conversations | ✓ | Every turn is sanitised (Move 3 multi-turn fix). One certificate per request. |
| Streaming responses (stream:true / SSE) | ! | OFF by default on hosted gateway.lucairn.eu; enable via STREAMING_ENABLED=true on self-hosted Lucairn. When enabled, per-chunk relinking + post-stream DLP audit. |
| Tool-use / function calling (tools, tool_choice) | ✕ Roadmap | Tool definitions and tool-call arguments are not sanitised today. Sending tool inputs through this endpoint is unsafe — use the DSA Proxy API for explicit field routing or wait for the roadmap update. |
| Prompt caching (cache_control) | ✕ Roadmap | Each request is processed independently so the per-call evidence stays valid. No cache reuse across requests. |
| Vision / images / files / batch | ✕ Roadmap | Only POST /v1/messages with text content is proxied today. Other Anthropic endpoints have no Lucairn pipeline coverage — do not send PII through them. |
Non-streaming messages (stream:false)
✓Full PII sanitisation across system prompt + every turn + signed Lucairn Certificate per request.
System prompts
✓System message is sanitised end-to-end alongside the user turns. Hard-identifier patterns in the system prompt are rejected with HTTP 400 — move PII into user messages.
Multi-turn conversations
✓Every turn is sanitised (Move 3 multi-turn fix). One certificate per request.
Streaming responses (stream:true / SSE)
!OFF by default on hosted gateway.lucairn.eu; enable via STREAMING_ENABLED=true on self-hosted Lucairn. When enabled, per-chunk relinking + post-stream DLP audit.
Tool-use / function calling (tools, tool_choice)
✕ RoadmapTool definitions and tool-call arguments are not sanitised today. Sending tool inputs through this endpoint is unsafe — use the DSA Proxy API for explicit field routing or wait for the roadmap update.
Prompt caching (cache_control)
✕ RoadmapEach request is processed independently so the per-call evidence stays valid. No cache reuse across requests.
Vision / images / files / batch
✕ RoadmapOnly POST /v1/messages with text content is proxied today. Other Anthropic endpoints have no Lucairn pipeline coverage — do not send PII through them.
Streaming-on-hosted, tool-use DLP, and vision are tracked on the roadmap. Subscribe to the changelog for ship dates. Read the changelog.
Compare other SDK paths
Want to see this in action?
Book a working session — we'll walk through your use case together.