Zum Hauptinhalt springen
Jeder Request, der OrcaRouter erreicht, trägt einen API-Key. Dieser Schlüssel ist nicht nur eine Credential — er ist eine Scope-Deklaration: welche Modelle der Aufrufer verwenden darf, welche IPs ihn präsentieren dürfen, wie viel er ausgeben darf und genau welches Guardrail und welche Firewall-Policy seinen Traffic steuern. Diese Seite erklärt die dreistufige Hierarchie und wie Policies zur Request-Zeit aufgelöst werden.

​
1. Die drei Scopes

Drei Konzepte verschachteln sich ineinander:
  • Workspace — die Tenant-Grenze. Jedes Mitglied eines Workspaces teilt denselben Guardrail- und Firewall-Policy-Katalog. Nichts überschreitet Workspace-Grenzen — eine Policy, die in Workspace A verfasst wurde, ist für Workspace B unsichtbar.
  • Policy — ein benannter, workspace-bezogener Regelsatz (Guardrail oder Firewall-Policy). Eine Policy zu bearbeiten wirkt sich auf jeden daran gebundenen Schlüssel beim nächsten Request aus, ohne Redeploy.
  • Key — Identität plus Bindungen. Ein Schlüssel trägt seine eigenen Einschränkungen und verweist auf die Policies, die ihn steuern.
Der Workspace ist die äußere Grenze; Policies sind geteilte Ressourcen darin; Schlüssel sind die per-Agenten-Identitäten, die Einschränkungen und Policies zusammenbinden.

​
2. Was ein Schlüssel enthält

Jeder API-Key ist ein Bündel von Limits und Bindungen. Setzen Sie diese im Key-Editor (/console/token) — das Erstellen oder Bearbeiten von Schlüsseln erfordert die Rolle Developer oder höher.
FeldWas es einschränktMindestrolle zum Setzen
model_limitsSchränkt den Schlüssel auf eine spezifische Liste von Modellen ein — jeder Aufruf außerhalb dieser Liste wird abgelehnt, bevor er das Gateway verlässt.Developer
allow_ipsIP-Allowlist. Requests von einer nicht gelisteten Adresse werden auf der Auth-Ebene abgelehnt. Leer bedeutet alle IPs sind erlaubt.Developer
credit_limit_usdAusgabenlimit in USD. 0 bedeutet unbegrenzt. Das Gateway setzt dies gegen die Lifetime-Ausgaben des Schlüssels durch.Developer
expired_timeAbsoluter Ablauf-Timestamp. -1 bedeutet der Schlüssel läuft nie ab.Developer
environmentEin Freitext-Label (z. B. prod, staging, dev) zum Organisieren von Schlüsseln und Filtern von Logs.Developer
guardrail_idBindet ein spezifisches Guardrail an diesen Schlüssel. Jeder Aufruf dieses Schlüssels wird durch dieses Guardrail geprüft.Developer
firewall_policy_idBindet eine spezifische Firewall-Policy an diesen Schlüssel. Jeder Tool-Call, den dieser Schlüssel ausgibt, wird durch diese Policy ausgewertet.Developer
is_firewall_gatewayMarkiert den Schlüssel als gateway-scoped Token — erforderlich, um die MCP-Dispatch- und Evaluate-Hook-Routen aufzurufen. Ein regulärer Schlüssel bekommt 403 auf diesen Routen. Den Klartext eines Gateway-Schlüssels lesen erfordert Admin.Admin (zum Aktivieren und zum Lesen des Klartexts)
Schlüssel werden in der Konsole maskiert angezeigt. Klartext wird einmalig bei der Erstellung angezeigt; Gateway-scoped Schlüssel erfordern Admin, um ihn erneut abzurufen.

​
3. Policy-Auflösungsreihenfolge

Für jeden Request löst OrcaRouter das aktive Guardrail und die Firewall-Policy unabhängig voneinander auf:
  1. Schlüssel-Bindung — wenn der Schlüssel eine explizite guardrail_id (oder firewall_policy_id) hat und diese Policy existiert und aktiviert ist, gilt sie.
  2. Workspace-Default — wenn der Schlüssel keine Bindung hat, gilt das aktivierte is_default-Guardrail (oder die -Policy) des Workspaces.
  3. Keine Durchsetzung — wenn keines gesetzt ist, wird der Request ohne Inhalts-Prüfung oder Tool-Call-Durchsetzung durchgelassen.
Die zwei Ebenen unterscheiden sich, wenn eine angehängte Policy deaktiviert ist:
  • Eine deaktivierte oder gelöschte Guardrail-Bindung bedeutet, dass der Schlüssel kein Guardrail bekommt — das Deaktivieren ist der Aus-Schalter; er fällt nicht auf den Workspace-Default zurück.
  • Eine deaktivierte Firewall-Bindung fällt auf die Workspace-Standard- Firewall-Policy zurück — das Deaktivieren einer Firewall-Bindung setzt den Schlüssel auf den Workspace-Default zurück, es schaltet die Durchsetzung nicht aus.
Eine fehlende (0/nicht gesetzt) Bindung fällt immer auf den Workspace-Default zurück; keines gesetzt bedeutet keine Durchsetzung.
Höchstens ein Guardrail und eine Firewall-Policy pro Workspace können zu jeder Zeit der Default sein. Das Promoten eines neuen Defaults degradiert das alte in derselben Transaktion — Sie können nie versehentlich zwei Defaults haben.

​
4. Least-Agency-Schlüssel — ein Schlüssel pro Agent

Die sicherste Konfiguration ist, jedem Agenten seinen eigenen eng geschnittenen Schlüssel zu geben, anstatt einen einzelnen Workspace-Schlüssel über alle Aufrufer zu teilen. Ein gut abgestimmter Schlüssel für einen Agenten, der nur ein Modell aufruft und geplante Aufgaben ausführt, könnte so aussehen:
  • model_limits: ["openai/gpt-4o-mini"] — der Agent kann nicht zu einem teureren oder fähigeren Modell wechseln.
  • allow_ips: das Egress-CIDR des Schedulers — keine andere Quelle kann diesen Schlüssel präsentieren.
  • credit_limit_usd: ein wöchentliches Budgetlimit — eine unkontrollierte Schleife kann Ihr Workspace-Guthaben nicht aufbrauchen.
  • expired_time: das Ende des Sprints oder des Deployment-Lebenszyklus — der Schlüssel läuft automatisch ab und kann nicht wiederverwendet werden.
  • guardrail_id: ein Guardrail, das auf die Datensensitivität dieses Agenten abgestimmt ist — strenger als der Workspace-Default.
  • firewall_policy_id: eine Policy, die nur die Tools erlaubt, die dieser Agent legitim benötigt.
Wenn dieser Agent über eine Prompt-Injection kompromittiert wird, ist der Schadensradius begrenzt: er kann nur ein Modell aufrufen, nur von einem IP-Bereich, nur bis zu seinem Ausgabenlimit und nur die Tools, die seine Firewall-Policy erlaubt. Der Rest des Workspaces ist nicht betroffen.
Erstellen Sie Gateway-scoped Schlüssel (is_firewall_gateway) nur für die MCP-Dispatch- oder Evaluate-Hook-Surface — niemals für allgemeinen Inference-Traffic. Ein Gateway-Schlüssel auf dem Inference-Pfad gibt dem Aufrufer Zugang zu /api/v1/firewall/*-Routen, was eine breitere Fähigkeit ist, als er benötigt. Ein Schlüssel, ein Zweck.

​
5. Wo Policies verfasst werden

Guardrails und Firewall-Policies sind beide workspace-bezogen und für alle Mitglieder geteilt, aber Änderungen erfordern die richtige Rolle:
  • Lesen eines Guardrails, einer Policy oder eines Schlüssels — jedes Workspace-Mitglied.
  • Erstellen oder Ändern von Guardrails, Firewall-Policies, MCP-Servern, Autonomie-Leveln, Freigabe-Aktionen und gewöhnlichen API-Schlüsseln — Developer+.
  • is_firewall_gateway aktivieren auf einem Schlüssel; den Klartext eines Gateway-Schlüssels lesen — Admin+.
Der Workspace ist die Zusammenarbeits-Grenze: jeder kann den Policy-Katalog sehen; nur Developer und höher können ihn ändern; nur Admins können Gateway-Credentials ausstellen.

​
6. Nächste Schritte

Secure-Agents-Baseline

Die empfohlene Ausgangshaltung — ein Autonomie-Level-Schalter, dann basierend auf echtem Traffic abstimmen.

Einen API-Key erhalten

Ihren ersten Schlüssel erstellen und ein Guardrail oder eine Firewall-Policy in der Konsole anbinden.
Scope ist das Fundament des Control-Stacks. Je enger der Scope jedes Schlüssels, desto kleiner der Schadensradius, wenn ein Agent kompromittiert wird — und desto klarer der Audit-Trail, der zeigt, wozu jeder Agent autorisiert war.