Salt la conținutul principal
Română— Alege o limbă
Meniu

Listarea și modificarea cheilor dumneavoastră

Lecția 3 din 14 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. Inventarul cheilor dumneavoastră API
  2. Listarea cheilor
  3. Modificarea unei chei existente
  4. Verificarea propagării
  5. Scenarii comune
  6. Puncte cheie

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-keys listează toate cheile cu paginare și filtrare ACL
  • PUT /auth/api-keys/{apiKeyId} modifică parametrii fără a schimba cheia secretă
  • GET /auth/api-keys/{apiKeyId}/propagation verifică 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