Authentifizierung & Header

Basis-URL und Schlüssel

Alle Endpunkte liegen unter der Basis-URL https://api.noirdoc.de/v1. Jede Anfrage braucht einen API-Schlüssel Ihrer Organisation. Sie erstellen ihn unter Models → API-Schlüssel.

API-Schlüssel beginnen mit px-. Senden Sie den Schlüssel in einem dieser drei Header:

Header	Form	Typischer Absender
`Authorization`	`Bearer px-...`	OpenAI-SDK, curl
`x-api-key`	`px-...`	Anthropic-SDK
`api-key`	`px-...`	Azure-OpenAI-Client

Alle drei Formen sind gleichwertig. Das Gateway prüft sie in der Reihenfolge der Tabelle und nimmt den ersten Header, dessen Wert mit px- beginnt. Ein Wert ohne dieses Präfix zählt als fehlender Schlüssel.

Shell

curl https://api.noirdoc.de/v1/models \
  -H "Authorization: Bearer $NOIRDOC_API_KEY"

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noirdoc.de/v1",
    api_key=os.environ["NOIRDOC_API_KEY"],
)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.noirdoc.de/v1",
  apiKey: process.env.NOIRDOC_API_KEY,
});

Fehlender oder ungültiger Schlüssel

Ohne gültigen Schlüssel antwortet das Gateway mit Statuscode 401 (Unauthorized). Diese Antwort hat nicht das übliche Fehlerobjekt, sondern ein Feld detail:

`detail`	Ursache
`Missing or invalid API key`	Kein Header mit einem Wert, der mit `px-` beginnt.
`Invalid or inactive API key`	Der Schlüssel ist unbekannt oder deaktiviert, oder die Organisation ist nicht aktiv.

Alle anderen Fehler des Gateways stehen unter Fehlercodes.

JSON

{
  "detail": "Invalid or inactive API key"
}

Maskierung pro Anfrage

Der Header X-Noirdoc-Mask schaltet die Maskierung für eine einzelne Anfrage ein oder aus. Erlaubt sind on und off, die Groß- und Kleinschreibung spielt keine Rolle. Andere Werte ignoriert das Gateway.

Ob der Header wirkt, legt die Maskierungsrichtlinie Ihrer Organisation fest (Models → Datenschutz):

Richtlinie	ohne Header	`on`	`off`
`default_off`	nicht maskiert	maskiert	nicht maskiert
`default_on`	maskiert	maskiert	nicht maskiert
`enforced`	maskiert	maskiert	maskiert

Neue Organisationen starten mit default_off. Das Gateway entfernt X-Noirdoc-Mask, bevor es die Anfrage weiterleitet. Der Anbieter sieht den Header nie.

Nur /v1/chat/completions, /v1/responses und /v1/messages können maskieren. Auf allen anderen modellbasierten Endpunkten lehnt das Gateway X-Noirdoc-Mask: on und die Richtlinie enforced mit Statuscode 403 und dem Code masking_not_supported_for_endpoint ab, statt die Anfrage unmaskiert weiterzuleiten. Dasselbe gilt für das Hochladen über /v1/files und das Anlegen von Skills. Bei default_on ohne Header leitet es Anfragen an diese Endpunkte unmaskiert weiter. Welche Felder maskiert werden, steht unter Maskierte Felder.

Shell

curl https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Noirdoc-Mask: on" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [{
      "role": "user",
      "content": "Was schreibt Herr Müller der Kanzlei?"
    }]
  }'

Python

response = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[
        {
            "role": "user",
            "content": "Was schreibt Herr Müller der Kanzlei?",
        }
    ],
    extra_headers={"X-Noirdoc-Mask": "on"},
)

TypeScript

const response = await client.chat.completions.create(
  {
    model: "qwen3.8-27b",
    messages: [
      {
        role: "user",
        content: "Was schreibt Herr Müller der Kanzlei?",
      },
    ],
  },
  { headers: { "X-Noirdoc-Mask": "on" } },
);

Anbieter der Antwort

Die Antwort enthält den Header X-Noirdoc-Provider. Er nennt den Anbieter, der die Anfrage beantwortet hat, als Kurznamen (Slug). Fällt das Gateway auf einen anderen Anbieter zurück (Failover), nennt der Header den Anbieter, der am Ende geantwortet hat.

Das Gateway setzt den Header

bei erfolgreichen Antworten, auch beim Streaming,
bei Fehlerantworten des Anbieters,
auf /v1/audio/speech und /v1/audio/transcriptions.

Der Header fehlt bei /v1/files und /v1/skills, bei Endpunkten, die keinen Anbieter aufrufen (/v1/models, /v1/prices, /v1/detect, /v1/pseudonymize), und bei Fehlern, die das Gateway selbst meldet (Fehlerobjekt mit "type": "proxy_error"). Wie das Gateway den Anbieter auswählt, erklärt Anbieter & Routing.

Shell

curl -si https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [{"role": "user", "content": "Hallo"}]
  }' \
  | grep -i x-noirdoc-provider

Python

raw = client.chat.completions.with_raw_response.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "Hallo"}],
)
print(raw.headers.get("x-noirdoc-provider"))
completion = raw.parse()

TypeScript

const { data, response } = await client.chat.completions
  .create({
    model: "qwen3.8-27b",
    messages: [{ role: "user", content: "Hallo" }],
  })
  .withResponse();
console.log(response.headers.get("x-noirdoc-provider"));

Maskierung in der Antwort

Der Antwort-Header X-Noirdoc-Masked zeigt mit true oder false, ob die Maskierung für die Anfrage aktiv war. Der Wert folgt aus der Maskierungsrichtlinie und dem Header X-Noirdoc-Mask, wie in der Tabelle oben. Er sagt nicht, ob das Gateway personenbezogene Daten gefunden hat.

Das Gateway setzt den Header auf jeder Antwort, die ein Anbieter geliefert hat: bei erfolgreichen Antworten, auch beim Streaming, und bei Fehlerantworten des Anbieters. Endpunkte ohne Maskierung (Embeddings, Audio, Bilder, /v1/files, /v1/skills) antworten immer mit false. Bei Fehlern, die das Gateway selbst meldet, fehlt der Header.

Auch bei true prüft das Gateway keine Dateien, auf die die Anfrage nur per file_id oder URL verweist, siehe Dateien.

Sendet ein Anbieter selbst Header namens X-Noirdoc-Masked oder X-Noirdoc-Provider, entfernt das Gateway sie. Beide Werte stammen immer vom Gateway.

Shell

curl -si https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Noirdoc-Mask: on" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [{"role": "user", "content": "Hallo"}]
  }' \
  | grep -i x-noirdoc-masked

Text

x-noirdoc-masked: true

Weitere Header

Das Gateway entfernt vor der Weiterleitung die drei Schlüssel-Header, X-Noirdoc-Mask und die Verbindungs-Header (etwa Host und Content-Length). Die Zugangsdaten für den Anbieter setzt es selbst. Alle übrigen Header reicht es an den Anbieter weiter, zum Beispiel anthropic-beta.

Ausnahme ist anthropic-version: Bei Anthropic setzt das Gateway diesen Header selbst auf 2023-06-01 und überschreibt Ihren Wert. Bei Claude-Modellen über Google Vertex AI entfernt es anthropic-version und anthropic-beta und überträgt die Beta-Kennungen in den Body, wie Vertex es verlangt.

Auswahl des Anbieters

Der Header, in dem Sie den Schlüssel senden, wählt keinen Anbieter. Auf allen modellbasierten Endpunkten entscheidet das Feld model zusammen mit dem Katalog Ihrer Organisation. Ausnahmen sind die Endpunkte ohne model: /v1/skills geht immer an Anthropic. Bei /v1/files bestimmt der Schlüssel-Header das API-Format: x-api-key wählt Anthropic, die beiden anderen Header wählen OpenAI. Der Header X-Provider kann das überschreiben. Details unter Dateien & Skills.