Schnellstart

Folgen Sie dem Authentifizierungsleitfaden, um sich anzumelden, öffnen Sie dann die Seite für Verwaltungsschlüssel und erstellen Sie einen Verwaltungsschlüssel. Bewahren Sie ihn getrennt von Standard-Anwendungsschlüsseln auf. Senden Sie ihn als Bearer-Token nur an Platform-Management-Endpunkte.

Ein Standard-API-Schlüssel kann keine Schlüssel- oder Guardrail-Verwaltungsendpunkte aufrufen. Ein gültiger Verwaltungsschlüssel kann trotzdem 403 Forbidden erhalten, wenn dessen Inhaber nicht mehr über die erforderliche Kontorolle verfügt.

Verwende GET /api/v1/keys, um die für das Verwaltungsschlüssel-Konto sichtbaren Schlüssel zu prüfen:

Verwende zurückgegebene öffentliche Bezeichner für spätere Abruf-, Aktualisierungs-, Widerrufs- oder Guardrail-Zuweisungsanfragen. Leite niemals Zugriff aus einem Schlüsselnamen oder einem maskierten Token ab.

Erstellen Sie einen Anwendungsschlüssel mit POST /api/v1/keys. Das vollständige Secret wird nur in der Erstellungsantwort zurückgegeben; speichern Sie es daher in Ihrem Secret-Manager, bevor Sie diese Antwort verwerfen. Die Rotation sollte einen Ersatzschlüssel erstellen, ihn in der Anwendung bereitstellen, den Traffic überprüfen und dann den alten Schlüssel widerrufen.

credit_limit_windows akzeptiert jede Kombination aus rollierenden Ausgabenlimits für 1h, 1d und 7d. Wenn ein konfiguriertes Fenster erschöpft ist, geben Aufrufe mit diesem Schlüssel 429 Too Many Requests zurück, bis der Verbrauch das Fenster verlässt. Senden Sie beim Aktualisieren eines Schlüssels ein leeres Objekt, um alle rollierenden Limits zu löschen.

Wenn eine Erstellungsanfrage alle Felder für Ausgabenlimits und guardrail_id auslässt, verwendet der neue Schlüssel die Governance-Standardwerte des Workspace. Explizite Limits, rollierende Zeitfenster oder ein Guardrail ersetzen diese Standardauswahl. Senden Sie credit_limit_cents: null, um ein unbegrenztes natives Limit zu erstellen. Ein angegebener Betrag ohne Rücksetzintervall bleibt ein Limit für die gesamte Laufzeit. Aktualisierungen wenden die Workspace-Standardwerte nie erneut an, und Änderungen der Standardwerte ändern keine bestehenden Schlüssel.

Erstellen und Aktualisieren akzeptieren tags, ein Array vollständiger key:value-Strings. Listen-, Abruf-, Erstellungs- und Aktualisierungsantworten liefern das vollständige Array. PATCH ersetzt das Array; wird tags weggelassen, bleibt es erhalten. Der Schlüssel muss 1–32 und der Wert 1–64 Zeichen umfassen, mit genau einem Doppelpunkt und ohne Leerraum. Höchstens 20 unterschiedliche Tags einschließlich Vorgaben sind zulässig. Ungültige Formate oder widersprüchliche Vorgaben liefern 422 mit Tag-Validierungsfehlern; ein Nicht-Array oder ein nicht als String vorliegendes Element liefert 400.

Genau ein Zweck-Tag ist erforderlich: usage:developer oder usage:service. Beim Erstellen über die Management API wird ohne angegebenen Zweck usage:service ergänzt, auch bei tags: []. Dashboard-Erstellung und Tag-Aktualisierungen ohne Zweck verwenden usage:developer. Bestehende Schlüssel werden als Developer migriert. Die Umgebung ist optional und erlaubt höchstens eines von env:production, env:staging oder env:dev (env:prod ist nicht zulässig).

Das Dashboard bietet beim Erstellen/Bearbeiten Zweck- und Umgebungsauswahl sowie benutzerdefinierte Tags und Vorschläge ausschließlich aus nicht verworfenen Standardschlüsseln des aktuellen Workspace. Listen zeigen Werte und beim Darüberfahren das vollständige Tag. Tags ändern weder Eigentümer noch Sichtbarkeit oder Berechtigungen eines Schlüssels. Tags können einen Schlüssel einem gemeinsamen Tag-Budget zuordnen.

Workspace-Administratoren legen die erforderlichen Tags eines Mitglieds in Team über das Mitgliedsbudgetformular fest. Erforderliche Tags sind benutzerdefinierte Tags mit Groß-/Kleinschreibung, etwa team:growth. Die Namensräume usage: und env: sind reserviert. Ein Mitglied kann höchstens 19 erforderliche Tags haben; pro Schlüssel gilt weiterhin ein Limit von insgesamt 20 Tags.

Jeder neue Standardschlüssel enthält automatisch die erforderlichen Tags seines Eigentümers im jeweiligen Workspace. Beim Erstellen werden eingereichte und erforderliche Tags vor der Validierung kombiniert. Benötigt das Mitglied beispielsweise team:growth, liefert eine Erstellungsanfrage der Management API mit tags: ["project:chatbot"] die Tags project:chatbot, team:growth und den Standardwert usage:service zurück.

Ein PATCH, der tags angibt, muss alle erforderlichen Tags beibehalten. Das Entfernen eines erforderlichen Tags liefert 422 mit einem Validierungsfehler, der die fehlenden Tags nennt, auch wenn der Aufrufer Administrator ist. Wird tags weggelassen, bleiben die Tags des Schlüssels erhalten. Mitglieder können gewöhnliche Tags weiterhin hinzufügen oder entfernen.

Um ein erforderliches Tag zu entfernen, ändert ein Administrator die Konfiguration des Mitglieds in Team. Beim Speichern werden neue erforderliche Tags allen bestehenden Standardschlüsseln dieses Mitglieds hinzugefügt und aufgehobene erforderliche Tags entfernt. Andere Tags bleiben unverändert. Dies gilt auch für deaktivierte und abgelaufene Schlüssel, jedoch nicht für gelöschte. Kann ein Schlüssel den endgültigen Tag-Satz nicht aufnehmen, schlägt der gesamte Speichervorgang fehl und das Formular nennt den zu korrigierenden Schlüssel.

Tag-Budgets verwenden die aktuellen Tags jedes Schlüssels. Änderungen erforderlicher Tags ändern auch die Budgetzuordnung bereits angefallener Ausgaben im aktuellen Zeitraum. Das Hinzufügen eines erforderlichen Tags kann dessen Budget sofort ausschöpfen. Bestehende Mitglieder beginnen ohne erforderliche Tags; ihre Schlüssel bleiben unverändert, bis ein Administrator eine Konfiguration speichert.

Guardrails sind wiederverwendbare Kontorichtlinien für Modell-, Anbieter- und Ausgabenkontrollen. Verwalten Sie Richtlinien über /api/v1/guardrails und verwenden Sie /api/v1/guardrail_assignments, um sie zuzuweisen oder zu entfernen. Behandeln Sie eine abgelehnte Zuweisung als Richtlinien- oder Eigentümerfehler, anstatt stillschweigend ohne den Guardrail fortzufahren.

Erstellen Sie eine positive Schutzregel im Modus block und ordnen Sie deren guardrail_id und ein groß-/kleinschreibungsabhängiges tag wie dept:ml zu. Wählen Sie genau ein Ziel, api_token_id, account_user_id oder tag. Tag-Budgets erfordern einen Administrator. Deaktivierte Budgets setzen keine Limits durch. Verwaltungsanfragen verbrauchen kein Budget.

Budgets aggregieren aktuelle Tags von Standardschlüsseln einschließlich Ausgaben gelöschter, deaktivierter und abgelaufener Schlüssel. Das Hinzufügen oder Entfernen eines Tags verschiebt die Ausgaben des Schlüssels im aktuellen Zeitraum. Das Erstellen oder Neuerstellen setzt Ausgaben nie zurück. Die Schlüsselanzahl schließt gelöschte Schlüssel aus. Jedes passende Budget muss die Anfrage zulassen; eine Ablehnung liefert 403 und den Tag-Namen.

Ein leeres credit_limit_reset_interval bedeutet ein dauerhaftes Limit. Andere Zeiträume verwenden UTC. Der Warnschwellenwert ist standardmäßig 80 und erlaubt 1 bis 100. Direkte Änderungen betreffen alle Zuordnungen; das Dashboard kopiert die Richtlinie vor der Bearbeitung eines Tag-Budgets.

Die Zulassung prüft Reservierungen. Die Abrechnung kann sie überschreiten, eine Nutzung über 100% anzeigen und weitere kostenpflichtige Anfragen sperren. Protokolle verwenden ihre Erstellungszeit; ausstehende Aufgaben und Batches ihre eigene. In einem früheren Zeitraum angenommene Aufgaben können später abgerechnet werden.