Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

API-kulcs létrehozása és konfigurálása

2. lecke 14 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Miért hozz létre kulcsokat az API-n keresztül?
  2. Létrehozási végpont
  3. Teljes példa curl-lel
  4. Ajánlott ACL stratégiák
  5. Elérhető ACL végpontok
  6. Főbb megállapítások

Miért hozz létre kulcsokat az API-n keresztül?

Egy kulcs kézi létrehozása harminc másodpercet vesz igénybe – pontosan ezért van szükséged automatizálásra. Mivel gyors, meggondolatlanul csinálod: nincs elnevezési konvenció, nincs sebességkorlátozás, csak egy „gyors haladást“ szolgáló helyettesítő karakter. Hat hónap múlva senki sem tudja, melyik kulcs mire való.

Az API használata arra kényszerít, hogy minden kulcsot elnevezz, hatókörrel láss el és korlátozz, mivel ezek a parancsfájl paraméterei. A következetesség megszűnik olyan fegyelem lenni, amit fenn kell tartanod, és a kód tulajdonságává válik. Automatizálhatod a kulcsok létrehozását a környezeteidhez (fejlesztés, tesztelés, éles), finomhangolt hozzáférés-szabályozást (ACL) alkalmazhatsz, és sebességkorlátokat definiálhatsz – mindezt a telepítési szkriptjeiden vagy infrastruktúra-kezelő eszközeiden belül.

Létrehozási végpont

API-kulcs létrehozásához küldj egy POST kérést a következő végpontra:

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

Kéréstörzs

{
  "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"
}

Részletes paraméterek

name (kötelező): a kulcsod olvasható azonosítója. Válassz leíró nevet, amely jelzi a felhasználást (prod-backend, staging-chatbot, dev-john). Ez a név megjelenik a konzolon és a használati naplókban is.

acls (kötelező): a kulcshoz rendelt engedélyek listája. Két formátum áll rendelkezésre:

  • api-key:endpoint:[végpont] – korlátozza az elérhető végpontokat (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[modell] – korlátozza a használható modelleket (grok-4.20-0309-reasoning, grok-4.3, stb.)

A * karakter helyettesítőként működik: az api-key:endpoint:* az összes végpontot, az api-key:model:* pedig az összes modellt engedélyezi. Ezt csak helyi fejlesztéshez tartalékold. Éles környezetben a helyettesítő karakter azt jelenti, hogy egy feltört kulcs hozzáférést biztosít mindenhez, amit a csapatod tehet – beleértve a legköltségesebb modelleket is, amelyeket az alkalmazásod talán sosem használ.

qps (opcionális): lekérdezés másodpercenként – a másodpercenkénti kérések maximális száma.

qpm (opcionális): lekérdezés percenként – a percenkénti kérések maximális száma.

tpm (opcionális): token percenként – a percenként feldolgozható tokenek maximális száma.

expireTime (opcionális): lejárati dátum ISO 8601 formátumban. A kulcs ezen a dátumon automatikusan letiltásra kerül.

Teljes példa curl-lel

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"
  }'

A válasz tartalmazza a titkos kulcsot, amelyet többé soha nem fognak megjeleníteni. Ennek a szabálynak gyakorlati következménye van, amire a szkript futtatása előtt, nem pedig után kell felkészülnöd: ha ciklusban hozol létre kulcsokat, a tárolásnak ugyanabban a műveletben meg kell történnie. A létrehozás és regisztrálás között elveszett kulcs nem állítható helyre – törölnöd kell, és elölről kezdeni. Írd ki egy titokkezelőbe (Vault, AWS Secrets Manager), ne a terminálod szabványos kimenetére, ahol bekerül a parancselőzményeidbe.

Ajánlott ACL stratégiák

Fejlesztői kulcs (széles körű)

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

Ideális helyi fejlesztéshez: a hozzáférés széles körű, mert előre nem tudod, mit fogsz kipróbálni, de a sebességkorlátok alacsonyak maradnak. Ez a helyes kompromisszum – egy péntek éjjel véletlenül írt végtelen ciklus néhány centbe kerül ahelyett, hogy néhány száz euróba.

Éles kulcs (korlátozott)

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

Éles környezetben a szabály megfordul: abból indulj ki, amit az alkalmazás valójában csinál, és csak azt engedélyezd. Az ACL írása során mindig ugyanazt a kérdést kell feltenned – ha ez a kulcs holnap szivárog ki, mit tud vele csinálni egy harmadik fél? Egy egyetlen modellre korlátozott, másodpercenként tíz kérésre limitált kulcsra adott válasz rövid.

Ideiglenes kulcs (lejártatható)

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

Az automatikus lejárat megoldja azt a problémát, amit senki sem kezel: a kulcsokat, amelyeket az emberek elfelejtenek törölni. Egy POC, egy bemutató, egy átmeneti vállalkozó – minden ilyen esetben az expireTime garantálja, hogy a hozzáférés önmagát kikapcsolja. Ez az egyetlen megbízható módja a tiszta leltár fenntartásának, mert nem támaszkodik senki memóriájára.

Elérhető ACL végpontok

Az ACL-ekben használható végpontok megtekintéséhez consultáld a következőt:

GET /auth/teams/{teamId}/endpoints

Az elérhető végpontok: chat, embed, image, models, sample, tokenize, documents. Ez a lista idővel változhat, ezért rendszeresen ellenőrizd.

Főbb megállapítások

  • A kulcs létrehozása a POST /auth/teams/{teamId}/api-keys végponton történik
  • Az ACL-ek formátuma api-key:endpoint:[név] vagy api-key:model:[név]
  • A * helyettesítő karakter teljes hozzáférést biztosít az összes végponthoz vagy modellhez
  • A titkos kulcs csak egyszer jelenik meg létrehozáskor – azonnal mentsd el
  • Mindig definiálj a használathoz igazított sebességkorlátokat (qps, qpm, tpm)
  • Használd az expireTime paramétert az ideiglenes kulcsoknál