API-Schlüssel auflisten und bearbeiten
Auf dieser Seite
Inventar Ihrer API-Schlüssel
Im Laufe der Zeit sammelt Ihr Team API-Schlüssel für verschiedene Umgebungen, Projekte und Teammitglieder. Die Management-API ermöglicht es Ihnen, alle aktiven Schlüssel aufzulisten, nach Berechtigungen zu filtern und deren Einstellungen zu ändern, ohne sie neu zu erstellen.
Schlüssel auflisten
Dieser Endpunkt ist der Ausgangspunkt für jede Zugriffsprüfung und ist oft der Ort, an dem Sie das tatsächliche Inventar entdecken: Schlüssel, die vor acht Monaten für Tests erstellt wurden, ein Schlüssel unter dem Namen eines ehemaligen Teammitglieds oder zwei Produktionsschlüssel, bei denen niemand weiß, welcher tatsächlich im Einsatz ist. Listen Sie vor dem Erstellen von etwas Neuem – der Schlüssel, den Sie benötigen, könnte bereits existieren.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Anforderungsparameter
- pageSize: Anzahl der Schlüssel pro Seite (standardmäßig werden alle Schlüssel zurückgegeben)
- paginationToken: Token zur Abrufung der nächsten Seite, wenn die Anzahl der Schlüssel die Seitengröße überschreitet
- aclFilters: Filtern Sie Schlüssel nach spezifischen Berechtigungen
Filterung nach ACL
Sie können nur Schlüssel mit einem bestimmten Zugriffsniveau abrufen:
# Listen Sie nur Schlüssel mit Chat-Zugriff auf
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Diese Filterung macht eine Prüfung auch bei mehr als einem Dutzend Schlüssel handhabbar. Zwei Fragen tauchen in der Praxis auf und werden durch eine einzige Anfrage beantwortet: Wer kann das teuerste Modell aufrufen, und welche Schlüssel tragen immer noch einen Wildcard-Zugriff? Die zweite Frage ist die nützlichste – ein vergessener Wildcard-Zugriff in der Produktion ist der häufigste Konfigurationsfehler und der stillste.
Paginierung
Für Teams mit vielen Schlüsseln nutzen Sie die Paginierung:
# Erste Seite mit 10 Schlüsseln
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Nächste Seite mit dem erhaltenen Token
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Bestehenden Schlüssel bearbeiten
Das Bearbeiten statt das Neuerstellen ist nicht nur eine Bequemlichkeit: Der geheime Schlüssel bleibt gleich, sodass keine Bereitstellung erforderlich ist. Dies ermöglicht es Ihnen, Limits anzupassen oder Berechtigungen einzuschränken ohne Dienstunterbrechung – und im Verdachtsfall die Rechte eines Schlüssels in Sekunden zu reduzieren, während Sie dessen Rotation vorbereiten.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v3",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 30,
"qpm": 1000,
"tpm": 3000000
}'
Bearbeitbare Parameter
- name: Umbenennen des Schlüssels, um eine Änderung der Nutzung widerzuspiegeln
- acls: Hinzufügen oder Entfernen von Berechtigungen (Endpunkte, Modelle)
- qps / qpm / tpm: Anpassen der Ratenlimits
- expireTime: Verlängern oder Verkürzen der Gültigkeitsdauer
Nicht bearbeitbare Parameter
- Die Schlüssel-ID (
api_key_id) bleibt fest - Der geheime Schlüssel ändert sich während der Bearbeitung nicht (dafür nutzen Sie die Rotation)
- Das Eigentum an dem Team kann nicht übertragen werden
Propagierung prüfen
Hier liegt der Detailgrad, der die Hälfte der nach einer Schlüsseländerung gemeldeten „Fehler” erklärt: Die Änderung ist nicht sofort auf allen Servern wirksam. Ein frisch erstellter Schlüssel kann für einige Momente eine 401-Fehlermeldung zurückgeben, und ein erweitertes ACL ist möglicherweise noch nicht aktiv – und Sie suchen den Fehler in Ihrem eigenen Code, obwohl Sie nur gewartet haben müssen. Der Propagierungs-Endpunkt existiert genau, um diesen Zweifel zu beseitigen:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Dieser Endpunkt gibt den Propagierungsstatus des Schlüssels zurück. Warten Sie, bis die Propagierung abgeschlossen ist, bevor Sie den Schlüssel in der Produktion verwenden, insbesondere nach Änderungen am ACL.
Häufige Szenarien
Dev-Schlüssel auf Prod aufrüsten
Der Wechsel in die Produktion ist das häufigste Szenario für Änderungen, und die Reflex, bei dieser Gelegenheit einen neuen Schlüssel zu erstellen, ist kostspielig: Sie müssen ihn überall bereitstellen, Vaults aktualisieren, und der alte bleibt unendlich lange bestehen. Das Anheben der Limits auf den bestehenden Schlüssel vermeidet all dies.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-chatbot",
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}'
Verdächtigen kompromittierten Schlüssel einschränken
Im Verdachtsfall ist die Reihenfolge der Operationen entscheidend. Einschränken Sie zuerst – leere ACLs, Ratenlimits auf Null – stoppen die Blutung mit einer einzigen Anfrage, ohne etwas Irreversibles zu beschädigen. Die Rotation erfolgt später, offline, sobald Sie identifiziert haben, wo der Schlüssel verwendet wurde. Das Umgekehrte lässt Sie mit einer ausgefallenen Produktion und einer Untersuchung unter Druck zurück.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"acls": [],
"qps": 0,
"qpm": 0
}'
Kernaussagen
GET /auth/teams/{teamId}/api-keyslistet alle Schlüssel mit Paginierung und ACL-Filterung aufPUT /auth/api-keys/{apiKeyId}ändert Parameter, ohne den geheimen Schlüssel zu verändernGET /auth/api-keys/{apiKeyId}/propagationverifiziert, dass Änderungen wirksam sind- Nutzen Sie ACL-Filterung, um regelmäßig den Zugriff Ihres Teams zu prüfen
- Prüfen Sie nach jeder Änderung die Propagierung, bevor Sie den Schlüssel in der Produktion verwenden