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.

1

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.

2

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.

3

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.

Environment variables
# 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-..."
Install
# Python
pip install anthropic

# TypeScript
npm install @anthropic-ai/sdk
Python — worked example (German medical PII)
import 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"])
TypeScript — worked example
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 (verify)
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.

  • 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.

Streaming-on-hosted, tool-use DLP, and vision are tracked on the roadmap. Subscribe to the changelog for ship dates. Read the changelog.

Want to see this in action?

Book a working session — we'll walk through your use case together.