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

API-kulcsaid listázása és módosítása

3. lecke 14 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. API-kulcsaid leltára
  2. Kulcsok listázása
  3. Meglévő kulcs módosítása
  4. Propagáció ellenőrzése
  5. Gyakori forgatókönyvek
  6. Főbb megállapítások

API-kulcsaid leltára

Idővel a csapatod különböző környezetekhez, projektekhez és csapattagokhoz tartozó API-kulcsokat halmoz fel. A Management API lehetővé teszi az összes aktív kulcs listázását, jogosultságok szerinti szűrését, valamint beállításaik módosítását újrateremtésük nélkül.

Kulcsok listázása

Ez a végpont kiindulópontja minden hozzáférés-ellenőrzésnek, és gyakran itt derül fény a valós leltárra: nyolc hónappal ezelőtt teszthez létrehozott kulcsok, egy volt csapattag nevén futó kulcs, vagy két éles kulcs, amelyekről senki sem tudja, melyik van használatban. Mielőtt bármit újat hoznál létre, listázd a meglévőket – lehet, hogy a szükséges kulcs már létezik.

curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Kérési paraméterek

  • pageSize: a laponként visszaadott kulcsok száma (alapértelmezésben az összes kulcs visszaadásra kerül)
  • paginationToken: token a következő lap lekéréséhez, ha a kulcsok száma meghaladja a lapméretet
  • aclFilters: kulcsok szűrése konkrét jogosultságok alapján

Szűrés ACL alapján

Csak bizonyos hozzáférési szinttel rendelkező kulcsokat kérdezhetsz le:

# Csak a chat hozzáféréssel rendelkező kulcsok listázása
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Ez a szűrés teszi kezelhetővé az ellenőrzést tucatnyi kulcs felett is. A gyakorlatban két kérdés merül fel gyakran, amelyekre egyetlen kéréssel választ kapsz: ki hívhatja meg a legdrágább modellt, és mely kulcsok tartalmaznak még wildcardot. Ez utóbbi a leghasznosabb – egy elfelejtett wildcard éles környezetben a leggyakoribb konfigurációs hiba, és egyben a legcsendesebb is.

Lapozás

Nagy számú kulccsal rendelkező csapatok használjanak lapozást:

# 10 kulcs első lapja
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Következő lap a kapott tokennel
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Meglévő kulcs módosítása

A módosítás az újrateremtés helyett nem csupán kényelmi szempont: a titkos kulcs változatlan marad, így nincs szükség új telepítésre. Ez lehetővé teszi a korlátok beállítását vagy a jogosultságok szűkítését szolgáltatáskiesés nélkül – gyanú esetén pedig másodpercek alatt csökkentheted egy kulcs jogait, miközben előkészíted annak cseréjét.

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

Mit módosíthatsz

  • name: nevezd át a kulcsot a használat változásának megfelelően
  • acls: jogosultságok hozzáadása vagy eltávolítása (végpontok, modellek)
  • qps / qpm / tpm: sebességkorlátok beállítása
  • expireTime: az érvényességi idő meghosszabbítása vagy lerövidítése

Mit nem módosíthatsz

  • A kulcs azonosítója (api_key_id) rögzített marad
  • A titkos kulcs nem változik módosítás során (erre a kulcscsere szolgál)
  • A tulajdonos csapat nem ruházható át

Propagáció ellenőrzése

Íme az a részlet, amely a kulcsmódosítás után jelentett „hibák“ felét megmagyarázza: a változás nem azonnal lép életbe minden szerveren. Egy frissen létrehozott kulcs néhány pillanatig 401-es hibát adhat vissza, egy kibővített ACL még lehet, hogy nem aktív – és te a saját kódodban keresed a hibát, amikor csak várnod kellett volna. A propagációs végpont pontosan ezért létezik, hogy eloszlassa ezt a kétséget:

curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Ez a végpont visszaadja a kulcs propagációs státuszát. Várd meg a propagáció befejeződését, mielőtt éles környezetben használnád a kulcsot, különösen az ACL-ek módosítása után.

Gyakori forgatókönyvek

Fejlesztői kulcs frissítése éles környezetre

Az éles környezetre való átállás a leggyakoribb módosítási eset, és az ilyenkor új kulcs létrehozására való reflexus költséges: mindenhol telepítened kell, frissítened a tárolókat, a régi kulcs pedig határozatlan ideig ott marad. A meglévő kulcs korlátainak növelése mindezt elkerüli.

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

Gyanúsított, feltört kulcs korlátozása

Gyanú esetén a műveletek sorrendje döntő fontosságú. Először korlátozz – üres ACL-ek, nulla sebességkorlát –, ez egyetlen kéréssel megállítja a vérzést anélkül, hogy visszafordíthatatlan kárt okozna. A kulcscsere később következik, offline módon, miután azonosítottad, hol használták a kulcsot. A fordított sorrend azzal jár, hogy az éles rendszer leáll, és nyomás alatt kell lefolytatnod a vizsgálatot.

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

Főbb megállapítások

  • A GET /auth/teams/{teamId}/api-keys listázza az összes kulcsot lapozással és ACL-szűréssel
  • A PUT /auth/api-keys/{apiKeyId} módosítja a paramétereket a titkos kulcs megváltoztatása nélkül
  • A GET /auth/api-keys/{apiKeyId}/propagation ellenőrzi, hogy a változások életbe léptek-e
  • Használj ACL-szűrést a csapatod hozzáféréseinek rendszeres ellenőrzéséhez
  • Bármilyen módosítás után ellenőrizd a propagációt, mielőtt éles környezetben használnád a kulcsot