Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Erstellen und konfigurieren eines API-Schlüssels

Lektion 2 von 14 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Warum man Schlüssel über die API erstellt
  2. Endpunkt zur Erstellung
  3. Vollständiges Beispiel mit curl
  4. Empfohlene ACL-Strategien
  5. Verfügbare ACL-Endpunkte
  6. Kernaussagen

Warum man Schlüssel über die API erstellt

Das manuelle Erstellen eines Schlüssels dauert etwa dreißig Sekunden – genau aus diesem Grund ist Automatisierung notwendig. Da der Vorgang so schnell ist, wird er oft ohne Nachdenken ausgeführt: Es gibt keine Namenskonvention, keine Rate-Limits, nur ein Wildcard, um „schnell voranzukommen”. Sechs Monate später weiß niemand mehr, was ein bestimmter Schlüssel tut.

Die Nutzung der API zwingt Sie, jeden Schlüssel zu benennen, zu beschränken und zu limitieren, da dies Parameter des Skripts sind. Konsistenz wird so nicht mehr zu einer Disziplin, die Sie pflegen müssen, sondern zu einer Eigenschaft des Codes. Sie können die Schlüsselgenerierung für Ihre Umgebungen (Entwicklung, Test, Produktion) automatisieren, granulare Zugriffsrechte (ACLs) anwenden und Rate-Limits definieren – alles innerhalb Ihrer Bereitstellungs-Skripte oder Infrastruktur-Tools.

Endpunkt zur Erstellung

Um einen API-Schlüssel zu erstellen, senden Sie eine POST-Anfrage an folgenden Endpunkt:

POST /auth/teams/{teamId}/api-keys

Anforderungsbody

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Detaillierte Parameter

name (erforderlich): ein lesbarer Identifier für Ihren Schlüssel. Wählen Sie einen beschreibenden Namen, der die Verwendung angibt (prod-backend, staging-chatbot, dev-john). Dieser Name erscheint im Konsolenbereich und in den Nutzungsprotokollen.

acls (erforderlich): die Liste der Berechtigungen, die diesem Schlüssel gewährt werden. Es stehen zwei Formate zur Verfügung:

  • api-key:endpoint:[endpoint] – beschränkt die zugänglichen Endpunkte (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] – beschränkt die nutzbaren Modelle (grok-4.20-0309-reasoning, grok-4.3 usw.)

Das Zeichen * fungiert als Wildcard: api-key:endpoint:* autorisiert alle Endpunkte, api-key:model:* alle Modelle. Reservieren Sie dies für die lokale Entwicklung. In der Produktion bedeutet ein Wildcard, dass ein kompromittierter Schlüssel Zugriff auf alles erhält, was Ihr Team tun kann – einschließlich der kostspieligsten Modelle, die Ihre Anwendung möglicherweise gar nicht nutzt.

qps (optional): Anfragen pro Sekunde – maximale Anzahl der Anfragen pro Sekunde.

qpm (optional): Anfragen pro Minute – maximale Anzahl der Anfragen pro Minute.

tpm (optional): Tokens pro Minute – maximale Anzahl der pro Minute verarbeiteten Tokens.

expireTime (optional): Ablaufdatum im ISO-8601-Format. Der Schlüssel wird an diesem Datum automatisch deaktiviert.

Vollständiges Beispiel mit curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

Die Antwort enthält den geheimen Schlüssel, der niemals erneut angezeigt wird. Diese Regel hat eine praktische Konsequenz, die Sie vor der Ausführung des Skripts antizipieren müssen, nicht danach: Wenn Sie Schlüssel in einer Schleife erstellen, muss die Speicherung im selben Schritt erfolgen. Ein zwischen Erstellung und Registrierung verloren gegangener Schlüssel ist nicht wiederherstellbar – Sie müssen ihn löschen und von vorne beginnen. Schreiben Sie ihn in ein Vault (Vault, AWS Secrets Manager) statt in die Standardausgabe Ihres Terminals, wo er in Ihrer Historie landen würde.

Empfohlene ACL-Strategien

Entwicklungsschlüssel (umfassend)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Ideal für die lokale Entwicklung: Der Zugriff ist umfassend, da Sie im Vorhinein nicht wissen, was Sie ausprobieren werden, aber die Rate-Limits bleiben niedrig. Dies ist der richtige Kompromiss – ein versehentlich geschriebener Endlosschritt am Freitagabend kostet dann ein paar Cent statt ein paar hundert Euro.

Produktionsschlüssel (eingeschränkt)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

In der Produktion kehrt sich die Regel um: Beginnen Sie damit, was die Anwendung tatsächlich tut, und autorisieren Sie nur dies. Die Frage, die Sie beim Schreiben der ACL immer stellen sollten, ist dieselbe: Wenn dieser Schlüssel morgen geleakt wird, was kann ein Dritter damit anstellen? Ein Schlüssel, der nur auf Chat für ein einzelnes Modell beschränkt ist und auf zehn Anfragen pro Sekunde limitiert, liefert eine kurze Antwort.

Temporärer Schlüssel (ablauffähig)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

Automatische Ablaufdaten lösen das Problem, das niemand handhabt: Schlüssel, die Menschen vergessen zu löschen. Ein POC, eine Demonstration, ein vorübergehender Auftragnehmer – in all diesen Fällen garantiert expireTime, dass der Zugriff sich selbst abschaltet. Dies ist der einzige zuverlässige Weg, um ein sauberes Inventar zu pflegen, da er nicht auf das Gedächtnis einer Person angewiesen ist.

Verfügbare ACL-Endpunkte

Um die Endpunkte einzusehen, die Sie in ACLs verwenden können, konsultieren Sie:

GET /auth/teams/{teamId}/endpoints

Die verfügbaren Endpunkte sind: chat, embed, image, models, sample, tokenize, documents. Diese Liste kann sich im Laufe der Zeit ändern, daher prüfen Sie sie regelmäßig.

Kernaussagen

  • Die Schlüssel-Erstellung erfolgt über POST /auth/teams/{teamId}/api-keys
  • ACLs folgen dem Format api-key:endpoint:[name] oder api-key:model:[name]
  • Das Wildcard * gewährt vollen Zugriff auf alle Endpunkte oder Modelle
  • Der geheime Schlüssel wird nur einmal bei der Erstellung angezeigt – speichern Sie ihn sofort
  • Definieren Sie stets Rate-Limits (qps, qpm, tpm), die der Nutzung entsprechen
  • Verwenden Sie expireTime für temporäre Schlüssel