Zum Hauptinhalt springen
Jede langlebige Anmeldeinformation sollte planmäßig ersetzt werden, und sofort bei jedem Hinweis auf Exposition. Der sichere Weg, API-Key-Anmeldeinformationen zu rotieren, besteht nie darin, einen Live-Schlüssel an Ort und Stelle zu mutieren — es ist, einen frischen zu prägen, Traffic darauf zu verschieben und den alten zurückzuziehen, sobald nichts mehr von ihm abhängt. In dieser Reihenfolge erledigt, gibt es nie einen Moment ohne funktionierenden Schlüssel. Diese Seite ist das Schritt-für-Schritt-Playbook. Für den weiteren Schlüssel-Lebenszyklus (erstellen / deaktivieren / löschen) siehe Schlüssel verwalten; für jedes Feld, das ein Schlüssel trägt, siehe Das Token-Objekt.
Alle Konsolen-Aktionen hier leben im Schlüssel-Bildschirm (/console/token) und laufen auf Ihrem Session-/Access-Token — nicht dem Relay-Schlüssel. Das Erstellen, Bearbeiten, Deaktivieren oder Löschen eines Schlüssels erfordert die Rolle Developer oder höher. Nur /v1/*-Inferenz-Aufrufe verwenden den sk-orca-…-Relay-Schlüssel.

​
1. Warum rotieren, und warum nie an Ort und Stelle

Ein Schlüssel auf OrcaRouter ist eine unveränderliche Identität, nicht nur ein String — er trägt seine eigene Modell-Allowlist, IP-Allowlist, Ausgabenlimit, Ablauf und Policy-Bindungen. Sie können das Secret-Material eines bestehenden Schlüssels nicht ändern; die Anmeldeinformation und die Beschränkungen werden bei der Erstellung zusammen ausgestellt. Also bedeutet „Rotieren” einen Nachfolger auszustellen und auf ihn zu migrieren. Tun Sie es:
  • in einer festen Taktung für jede Produktions-Anmeldeinformation (vierteljährlich ist eine gängige Baseline);
  • in dem Moment, in dem ein Schlüssel als geleakt vermutet wird — wobei Sie ihn bei einem bestätigten Leak zuerst kappen und als Zweites rotieren (siehe Reaktion auf geleakte Schlüssel);
  • wann immer sich der Besitzer des Schlüssels (ein Mitarbeiter, eine Lieferanten-Integration, ein außer Dienst gestellter Agent) ändert.
Der Klartext (sk-orca-…) wird einmal gezeigt, bei der Erstellung — kopieren Sie ihn dann. Danach zeigt die Konsole nur eine maskierte Form wie orca-7Bf****wxyz. Ein Developer+ kann den Klartext eines gewöhnlichen Schlüssels später erneut einblenden, aber ein gateway-scoped Schlüssel (is_firewall_gateway) erfordert Admin, um seinen Klartext erneut zu lesen — behandeln Sie das erste Einblenden des Gateway-Schlüssels also als Ihre einzige zuverlässige Kopie.

​
2. Die Schlüsselrotations-Sequenz

Der ganze Punkt ist eine saubere Überlappung: Der neue Schlüssel funktioniert, bevor der alte stoppt. Vier Schritte.
1

Den Nachfolge-Schlüssel erstellen

Prägen Sie einen neuen Schlüssel mit dem gleichen Scope wie der, den Sie ersetzen — denselben model_limits, allow_ips, credit_limit_usd, expired_time und dieselbe guardrail_id / firewall_policy_id. Kopieren Sie den Klartext sofort. Die Rotation ist auch der ideale Moment, um den Scope zu verschärfen: Lassen Sie ein Modell fallen, das der Agent nicht mehr verwendet, oder verengen Sie die IP-Allowlist.
2

Traffic migrieren

Deployen Sie den neuen sk-orca-… an jeden Aufrufer — Konfiguration, Secret-Manager, CI-Variable, Agenten-Runtime. Rollen Sie ihn auf dieselbe Weise aus, wie Sie jede Secret-Änderung ausliefern. Beide Schlüssel sind an diesem Punkt live, sodass Deployments ohne Ausfall gestaffelt werden können.
3

Verifizieren, dass der neue Schlüssel Last trägt

Bestätigen Sie, dass der Nachfolger tatsächlich Traffic bedient, bevor Sie den alten anfassen. Beobachten Sie, wie das used_quota des neuen Schlüssels steigt, während das des alten Schlüssels abflacht — die Pro-Schlüssel-Nutzung ist Ihr Cutover-Signal.
4

Den alten Schlüssel zurückziehen

Sobald der alte Schlüssel keinen Traffic zeigt, deaktivieren Sie ihn zuerst (umkehrbar) und passen auf Nachzügler auf, dann löschen Sie ihn endgültig. Deaktivieren ist die Pause; Löschen ist der Punkt ohne Wiederkehr.
Setzen Sie ein environment-Label auf jeden Schlüssel — verwenden Sie es über den alten und neuen Schlüssel hinweg wieder oder erhöhen Sie es (prod → prod-2026q2) — sodass Nachfolger und Vorgänger distinkt beschriftet sind, während beide während des Überlappungsfensters live sind.

​
3. Eine konkrete Rotation, via REST

Alles unten ist eine Konsolen-Aktion — diese Management-Routen laufen unter Ihrer Session (UserAuth), nicht dem Relay-Schlüssel. Angenommen, Sie ersetzen den Schlüssel für einen geplanten Summarizer-Agenten. Erstellen Sie den Nachfolger mit dem gleichen Scope: 
# Konsolen-Session-Token — KEIN sk-orca-…-Relay-Schlüssel
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
Die Antwort gibt den Klartext einmal zurück ("data": "sk-orca-…"). Kopieren Sie ihn, deployen Sie ihn auf den Summarizer und bestätigen Sie, dass der neue Schlüssel bedient, bevor Sie weitermachen. Wenn der alte Schlüssel (id 481) keinen Traffic zeigt, deaktivieren, dann löschen Sie ihn: 
# Zuerst pausieren (umkehrbar) — den Status des alten Schlüssels auf Disabled (2) setzen
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Sobald Sie sicher sind, dass nichts von ihm abhängt — endgültig widerrufen
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
Der Status eines Schlüssels ist einer von Enabled (1), Disabled (2), Expired (3) oder Exhausted (4). Das Deaktivieren setzt ihn auf Disabled; jeder Request, den der Schlüssel stellt, wird dann abgelehnt, während seine Konfiguration, Bindungen und Historie intakt bleiben. Das Löschen ist permanent — die Anmeldeinformation kann nie wieder einen Request autorisieren, und ein gelöschter Schlüssel ist nicht wiederherstellbar.
Sie können all dies ohne die API tun — der Schlüssel-Bildschirm hat Neuer Schlüssel, einen Pro-Schlüssel-Disabled-Toggle und Löschen (einzeln oder Batch). Die obige REST-Form ist zum Skripten geplanter Rotationen.

​
4. Policy-gebundene und Gateway-Schlüssel rotieren

Die Guardrail- und Firewall-Bindungen eines Schlüssels leben auf dem Schlüssel, sodass der Nachfolger dieselbe guardrail_id und firewall_policy_id tragen muss, um dieselbe Haltung durchzusetzen. Zwei Dinge, die man wissen sollte:
Guardrails und Firewall-Policies sind workspace-bezogene, benannte Ressourcen, die über Schlüssel hinweg geteilt werden. Das Rotieren eines Schlüssels fasst die Policy selbst nicht an; Sie richten lediglich einen frischen Schlüssel erneut auf die bestehende guardrail_id / firewall_policy_id. Die Policy steuert den Traffic ununterbrochen weiter.
Ein Schlüssel mit gesetztem is_firewall_gateway treibt die Firewall-Gateway-Routen (/api/v1/firewall/*). Einen zu prägen und seinen Klartext erneut einzublenden, erfordern beide Admin. Weil Sie sein Secret nicht beiläufig erneut lesen können, erfassen Sie den Klartext des neuen Gateway-Schlüssels bei der Erstellung und speichern Sie ihn in Ihrem Secret-Manager, bevor Sie umstellen.
Verwenden Sie keinen einzelnen Schlüssel — Gateway oder nicht — über viele Agenten hinweg wieder und „rotieren” Sie, indem Sie Limits bearbeiten. Ein Schlüssel pro Agent hält jede Rotation isoliert und den Blast-Radius klein. Siehe die Least-Agency-Checkliste.

​
5. Notfall-Rotation (vermuteter Leak)

Wenn Sie denken, dass ein Schlüssel exponiert ist, kehrt sich die Reihenfolge um: stoppen Sie zuerst die Blutung, migrieren Sie als Zweites.
  1. Deaktivieren Sie den verdächtigen Schlüssel sofort, sodass er nichts autorisieren kann, während Sie untersuchen — oder löschen Sie ihn rundheraus, wenn der Leak bestätigt ist.
  2. Prägen Sie den Nachfolger und rollen Sie ihn aus wie in §2.
  3. Prüfen Sie, was der geleakte Schlüssel getan hat, bevor Sie ihn kappen: Filtern Sie die Request-Logs nach diesem Schlüssel (Token), um den Blast-Radius zu fassen.
Das vollständige Incident-Runbook ist auf Reaktion auf geleakte Schlüssel.
Eine kurze expired_time ist Rotations-Versicherung: Ein ablaufender Schlüssel zieht sich selbst zurück, selbst wenn Sie die manuelle Rotation vergessen, und begrenzt, wie lange eine einzelne Anmeldeinformation je missbraucht werden kann.

​
6. Nächste Schritte

Schlüssel verwalten

Der erstellen / deaktivieren / widerrufen-Lebenszyklus, auf dem diese Schritte aufbauen.

Policies an einen Schlüssel binden

Tragen Sie dasselbe Guardrail und dieselbe Firewall-Policy auf den Nachfolger.

Ablaufende Schlüssel

Setzen Sie einen Ablauf, sodass Schlüssel sich selbst zu einer Deadline rotieren.

Reaktion auf geleakte Schlüssel

Der Notfall-Pfad, wenn eine Anmeldeinformation exponiert ist.
Rotation ist nur disziplinierte Überlappung: ein Nachfolger, der funktioniert, bevor der Vorgänger stoppt. Halten Sie jeden Schlüssel eng gefasst, und die Übergabe bleibt langweilig — was genau das ist, was Sie von einer Anmeldeinformations-Rotation wollen.