API-kulcsaid listázása és módosítása
Ezen az oldalon
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-keyslistá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}/propagationellenő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