Listarea și modificarea cheilor dumneavoastră
Pe această pagină
Inventarul cheilor dumneavoastră API
În timp, echipa dumneavoastră acumulează chei API pentru diferite medii, proiecte și membri ai echipei. API-ul de Management vă permite să listați toate cheile active, să le filtrați după permisiuni și să le modificați setările fără a fi nevoie să le recreați.
Listarea cheilor
Acest punct final este punctul de plecare pentru orice audit de acces și este adesea locul unde descoperiți inventarul real: chei create pentru un test acum opt luni, o cheie pe numele unui fost membru al echipei, două chei de producție despre care nimeni nu știe care este în uz. Listați înainte de a crea orice nou – cheia de care aveți nevoie ar putea exista deja.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Parametrii cererii
- pageSize: numărul de chei pe pagină (implicit, sunt returnate toate cheile)
- paginationToken: token pentru a recupera pagina următoare dacă numărul de chei depășește dimensiunea paginii
- aclFilters: filtrează cheile după permisiuni specifice
Filtrare după ACL
Puteți recupera doar cheile cu un anumit nivel de acces:
# Listează doar cheile cu acces la chat
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Această filtrare este ceea ce face un audit gestionabil dincolo de o duzină de chei. Două întrebări apar în practică și sunt răspunse printr-o singură cerere: cine poate apela modelul cel mai scump și care chei mai conțin încă un wildcard. A doua este cea mai utilă – un wildcard uitat în producție este cea mai frecventă eroare de configurare și cea mai discretă.
Paginare
Pentru echipele cu multe chei, utilizați paginarea:
# Prima pagină de 10 chei
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Pagina următoare cu token-ul primit
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Modificarea unei chei existente
Modificarea în loc de recreare nu este doar o conveniență: cheia secretă rămâne aceeași, deci nu este necesară nicio implementare. Acest lucru vă permite să ajustați limitele sau să restricționați permisiunile fără întreruperea serviciului – și, în caz de suspiciune, să reduceți drepturile unei chei în câteva secunde în timp ce pregătiți rotația acesteia.
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
}'
Ce puteți modifica
- name: redenumiți cheia pentru a reflecta o schimbare în utilizare
- acls: adăugați sau eliminați permisiuni (puncte finale, modele)
- qps / qpm / tpm: ajustați limitele de rată
- expireTime: prelungiți sau scurtați perioada de valabilitate
Ce nu puteți modifica
- Identificatorul cheii (
api_key_id) rămâne fix - Cheia secretă nu se schimbă în timpul modificării (utilizați rotația pentru aceasta)
- Echipa proprietară nu poate fi transferată
Verificarea propagării
Iată detaliul care explică jumătate din „erorile“ raportate după modificarea unei chei: schimbarea nu este instantanee pe toate serverele. O cheie creată recent ar putea returna 401 pentru câteva momente, un ACL extins ar putea să nu fie încă activ – și căutați eroarea în propriul cod când trebuia doar să așteptați. Punctul final de propagare există tocmai pentru a elimina această îndoială:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Acest punct final returnează starea de propagare a cheii. Așteptați ca propagarea să se finalizeze înainte de a utiliza cheia în producție, în special după modificarea ACL-urilor.
Scenarii comune
Actualizarea unei chei de dezvoltare pentru producție
Trecerea la producție este cel mai frecvent scenariu de modificare, iar reflexul de a crea o cheie nouă cu această ocazie este costisitor: trebuie să o implementați peste tot, să actualizați seifurile (vaults), iar cea veche rămâne la infinit. Creșterea limitelor cheii existente evită toate acestea.
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
}'
Restricționarea unei chei suspectate de compromis
În caz de suspiciune, ordinea operațiunilor contează. Restricționarea mai întâi – ACL-uri goale, limite de rată zero – oprește sângerarea într-o singură cerere, fără a strica nimic ireversibil. Rotația vine mai târziu, offline, odată ce ați identificat unde a fost utilizată cheia. Inversul vă lasă cu producția oprită și o anchetă de condus sub presiune.
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
}'
Puncte cheie
GET /auth/teams/{teamId}/api-keyslistează toate cheile cu paginare și filtrare ACLPUT /auth/api-keys/{apiKeyId}modifică parametrii fără a schimba cheia secretăGET /auth/api-keys/{apiKeyId}/propagationverifică dacă modificările sunt efective- Utilizați filtrarea ACL pentru a audita regulat accesul echipei dumneavoastră
- După orice modificare, verificați propagarea înainte de a utiliza cheia în producție