Seznam in spreminjanje vaših ključev
Na tej strani
Pregled vaših API ključev
Sčasoma si vaša ekipa nabere API ključe za različna okolja, projekte in člane ekipe. Upravljalni API vam omogoča izpis vseh aktivnih ključev, filtriranje po dovoljenjih in spreminjanje njihovih nastavitev brez potrebe po ponovnem ustvarjanju.
Izpis ključev
Ta končna točka je izhodišče za vsak revizijski pregled dostopa in pogosto razkrije dejansko stanje: ključe, ustvarjene pred osmimi meseci za testiranje, ključ na ime nekdanjega člana ekipe ali dva produkcijska ključa, pri katerih nihče ne ve, kateri je v uporabi. Preden ustvarite kaj novega, najprej naredite seznam – morda ključ, ki ga potrebujete, že obstaja.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Parametri zahtevka
- pageSize: število ključev na stran (privzeto so vrnjeni vsi ključi)
- paginationToken: žeton za pridobitev naslednje strani, če število ključev preseže velikost strani
- aclFilters: filtriranje ključev po določenih dovoljenjih
Filtriranje po ACL
Pridobite lahko le ključe z določeno ravnjo dostopa:
# Izpiši samo ključe z dostopom do klepeta
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
To filtriranje omogoča obvladljivo revizijo tudi pri več kot ducatu ključev. V praksi se pojavita dve vprašanji, na katera odgovori en sam zahtevek: kdo lahko kliče najdražji model in kateri ključi še vedno vsebujejo nadomestni znak. Drugo vprašanje je najbolj koristno – pozabljen nadomestni znak v produkciji je najpogostejša napaka v konfiguraciji in hkrati najbolj tiha.
Paginacija
Za ekipe z velikim številom ključev uporabite paginacijo:
# Prva stran z 10 ključi
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Naslednja stran s prejetim žetonom
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Spreminjanje obstoječega ključa
Spreminjanje namesto ponovnega ustvarjanja ni zgolj priročno: skrivni ključ ostane enak, zato ponovna namestitev ni potrebna. To vam omogoča prilagoditev omejitev ali omejitev dovoljenj brez prekinitve storitve – v primeru suma pa lahko v nekaj sekundah zmanjšate pravice ključa, medtem ko pripravljate njegovo zamenjavo.
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
}'
Kaj lahko spremenite
- name: preimenujte ključ, da odraža spremembo uporabe
- acls: dodajte ali odstranite dovoljenja (končne točke, modeli)
- qps / qpm / tpm: prilagodite omejitve hitrosti
- expireTime: podaljšajte ali skrajšajte obdobje veljavnosti
Česa ne morete spremeniti
- Identifikator ključa (
api_key_id) ostane nespremenjen - Skrivni ključ se med spreminjanjem ne spremeni (za to uporabite zamenjavo)
- Lastniške ekipe ni mogoče prenesti
Preverjanje širjenja
Tukaj je podrobnost, ki pojasnjuje polovico „napak”, prijavljenih po spremembi ključa: sprememba ni takojšnja na vseh strežnikih. Na novo ustvarjen ključ lahko za nekaj trenutkov vrne napako 401, razširjeni ACL morda še ni aktiven – in vi iščete napako v svoji kodi, čeprav bi morali le počakati. Končna točka za širjenje obstaja prav zato, da odpravi ta dvom:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Ta končna točka vrne stanje širjenja ključa. Pred uporabo ključa v produkciji, zlasti po spremembi ACL-jev, počakajte, da se širjenje zaključi.
Pogosti scenariji
Nadgradnja razvojnega ključa v produkcijskega
Prehod v produkcijo je najpogostejši scenarij spreminjanja, refleks ustvarjanja novega ključa ob tej priložnosti pa je drag: namestiti ga morate povsod, posodobiti trezorje, stari ključ pa ostane nedoločen čas. Zvišanje omejitev obstoječega ključa vse to prepreči.
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
}'
Omejitev suma kompromitiranega ključa
V primeru suma je vrstni red operacij ključen. Najprej omejite – prazni ACL-ji, ničelne omejitve hitrosti – kar v enem zahtevku ustavi uhajanje, ne da bi kaj nepovratno pokvarili. Zamenjava sledi kasneje, offline, ko ugotovite, kje je bil ključ uporabljen. Obratni vrstni red pusti produkcijo nedelujočo in preiskavo, ki jo morate opraviti pod pritiskom.
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
}'
Ključne ugotovitve
GET /auth/teams/{teamId}/api-keysizpiše vse ključe s paginacijo in filtriranjem po ACLPUT /auth/api-keys/{apiKeyId}spremeni parametre brez spreminjanja skrivnega ključaGET /auth/api-keys/{apiKeyId}/propagationpreveri, ali so spremembe učinkovite- Uporabite filtriranje po ACL za redno revizijo dostopa vaše ekipe
- Po vsaki spremembi pred uporabo ključa v produkciji preverite širjenje