Skip to main content

​
Übersicht

Die Seite Users macht aus der user_path-Hierarchie hinter Ihren API-Keys einen Baum aus Gruppen und Benutzern und erlaubt es, für jeden Knoten einzuschränken, welche Modelle Requests darunter aufrufen dürfen:
  • /acme und /acme/eng sind Gruppen – sie enthalten weitere Pfade.
  • /acme/eng/alice ist ein Benutzer – API-Keys sind direkt daran gebunden.
Nichts muss vorab angelegt werden. Der Baum wird aus den User Paths bestehender API-Keys abgeleitet; fügen Sie einem Knoten nur dann eine Richtlinie hinzu, wenn Sie ihn einschränken möchten.

​
Regeln

  1. Neue Keys und Knoten erlauben alles. Ein Knoten oder Key ohne allowed_models legt selbst keine Einschränkung fest.
  2. Das Auflisten von Modellen schränkt ein. Sobald ein Knoten Modelle auflistet, dürfen Requests darunter nur Modelle verwenden, die zu dieser Liste passen.
  3. Listen werden im Baum nach unten geschnitten. Ein Request muss die Allowlist seines API-Keys, seines User Paths und jedes übergeordneten Knotens bis / erfüllen. Ein untergeordneter Knoten kann das, was seine Gruppe erlaubt, einschränken, aber niemals erweitern.
  4. Modellseitige Regeln gelten weiterhin. Eine Zugriffsrichtlinie eines virtuellen Modells, die ein Modell vor einem Teilbaum verbirgt, verbirgt es weiterhin.
GET /v1/models liefert nur die Modelle, die der Aufrufer verwenden darf, sodass Clients dasselbe Bild sehen, das das Gateway durchsetzt. Requests, die auf anderem Weg authentifiziert werden, folgen denselben Pfadregeln: Eine OIDC-SSO-Session oder ein Request, der nur den User-Path-Header mitbringt, wird durch die Richtlinien auf seinem user_path eingeschränkt; nur verwaltete API-Keys bringen zusätzlich eine Allowlist pro Key mit. Der Master-Key hat keinen gebundenen User Path: Ohne den Header ist er uneingeschränkt, mit dem Header wird er wie jeder andere Request auf diesem Pfad eingeschränkt.

​
Wie der Zugriff ermittelt wird

Richtlinien hängen am Baum der User Paths und werden von oben nach unten kombiniert. Jede Liste auf dem Weg von der Wurzel zum Pfad des Requests muss passen, und die eigene Liste des API-Keys wird zuletzt angewendet: Für einen einzelnen Request prüft das Gateway der Reihe nach: Woher die einzelnen Bausteine stammen: Ein Knoten ohne Liste trägt nichts zur Kette bei; er erweitert nichts und schränkt nichts ein. Deshalb hat ein neuer Key oder eine neue Gruppe zunächst Zugriff auf alles, und deshalb sieht /acme/sales oben weiterhin beide Provider.

​
Selektoren

Jeder Eintrag in einer Allowlist ist ein Selektor: Provider-Namen müssen einem konfigurierten Provider entsprechen; unbekannte Namen werden beim Speichern der Richtlinie abgelehnt. Virtuelle Modelle sind keine Selektoren: Ein Alias oder ein Load Balancer wird vor der Prüfung in das konkrete Provider-Modell aufgelöst. Erlauben Sie daher die Zielmodelle, nicht das virtuelle Modell. Ein Name eines virtuellen Modells in einer Liste wird als reine Modell-ID akzeptiert, passt aber nie auf etwas. Ein Load Balancer, dessen Ziele sich über mehrere Provider erstrecken, ist nur nutzbar, wenn jedes Ziel, das er wählen kann, erlaubt ist; andernfalls schlagen Requests mit 400 fehl, sobald er ein nicht erlaubtes Ziel wählt. Der Benutzerbaum zeigt einen solchen Knoten mit einer leeren effektiven Liste.

​
Beispiel

Ein an /acme/eng/alice gebundener API-Key mit eigenem allowed_models: [anthropic/claude-sonnet-4-6] schränkt Alice weiter auf dieses eine Modell ein. Ein abgelehnter Request erhält 400 mit dem Code model_access_denied.

​
Richtlinien verwalten

​
Dashboard

Users listet jeden Knoten mit seiner eigenen Allowlist, seinen effective models – dem Ergebnis auf Pfadebene, nachdem seine eigene Liste, die Listen aller übergeordneten Knoten und die modellseitigen Richtlinien virtueller Modelle angewendet wurden (ein rotes None kennzeichnet einen Knoten, dessen Listen keine gemeinsame Schnittmenge haben) – und der Anzahl der daran gebundenen API-Keys. Die eigenen allowed_models eines verwalteten API-Keys können einen Request weiter einschränken, als der Pfad anzeigt. Der Editor warnt bereits während der Eingabe, wenn die Liste kein Modell mehr übrig lassen würde. Fügen Sie einen Knoten hinzu oder bearbeiten Sie ihn, um seine Modelle festzulegen; entfernen Sie die Richtlinie, um auf die Limits der übergeordneten Knoten zurückzufallen. Die Anzahl der Keys verlinkt auf die Seite API Keys, gefiltert auf den Teilbaum dieses Pfads, und jede Zeile hat eine Aktion Add API key, die das Formular zum Anlegen eines Keys mit vorausgefülltem Pfad öffnet. Allowlists pro Key befinden sich auf der Seite API Keys: Setzen Sie Allowed models beim Anlegen eines Keys oder bearbeiten Sie sie später in der Zeile des Keys. Die Spalte Effective models dort ist die endgültige Antwort für diese Zugangsdaten – Pfadrichtlinien, die eigene Liste des Keys und modellseitige Richtlinien kombiniert.

​
Konfiguration

Deklarieren Sie Richtlinien in config.yaml unter users: (siehe Beispiel oben) oder in der Umgebungsvariable USERS als JSON-Array mit denselben Feldern:
Deklarierte Richtlinien überdecken Dashboard-Zeilen für denselben Pfad und sind im Dashboard schreibgeschützt. Ein falsch geschriebener Provider in einer deklarierten Richtlinie lässt den Start fehlschlagen.

​
Admin API

POST /admin/auth-keys akzeptiert allowed_models beim Anlegen. Request- und Response-Formate finden Sie unter Admin-Endpunkte.
Zuletzt geändert am 24. Oktober 2026