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

Rotația cheilor și ciclul de viață

Lecția 7 din 12 Actualizată 28 iulie 2026 Avansat
Pe această pagină
  1. De ce este esențială rotația cheilor
  2. Rotația prin API-ul de Management
  3. Ciclul complet de viață al unei chei
  4. Ce strategie de rotație ar trebui să adoptați?
  5. Douăzeci de minute pentru a recâștiga controlul inventarului dumneavoastră
  6. Puncte cheie

De ce este esențială rotația cheilor

O obiecție frecventă în sesiunile de formare este: „Cheia mea nu a fost niciodată compromisă, de ce să o schimb?“ Răspunsul se rezumă la un singur cuvânt: incertitudine. Nu puteți dovedi niciodată că o cheie nu a fost expusă—un jurnal verbose uitat pe un server, o captură de ecran partajată într-un tichet de suport, o stație de lucru de dezvoltator compromisă acum șase luni. Rotația regulată transformă această incertitudine într-un risc delimitat: chiar dacă o cheie a fost copiată fără știrea dumneavoastră, aceasta va înceta să funcționeze la următoarea rotație. Acesta este exact raționamentul utilizat de auditorii SOC 2; ei se așteaptă la o politică de rotație documentată. Aceasta este ceea ce numim reducerea suprafeței de atac temporale: cu cât o cheie trăiește mai mult, cu atât fereastra de exploatare pentru o compromitere silențioasă este mai mare.

API-ul de Management xAI este conceput pentru a face această practică nedureroasă: oferă un endpoint dedicat care vă permite să rotiți o cheie fără a rescrie configurațiile dumneavoastră.

Rotația prin API-ul de Management

Endpoint-ul de rotație este simplu:

POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate

Asigurați-vă că înțelegeți ce face acest apel înainte de a-l utiliza: generează o nouă cheie secretă pentru ID-ul existent și invalidează permanent cea veche, păstrând în același timp ACL-urile, limitele de rată și configurațiile atașate cheii. Ceea ce ia echipele prin surprindere prima dată este faptul că schimbarea este imediată și ireversibilă. Dacă backend-ul dumneavoastră de producție utilizează această cheie când declanșați rotația, acesta va începe să primească erori de autentificare în câteva secunde. Nu există o perioadă de grație, nici o modalitate de a reveni la starea anterioară.

De aceea, în producție, preferați în general o procedură în doi pași pentru a evita orice întrerupere. Mai întâi, creați o nouă cheie prin POST /auth/teams/{teamId}/api-keys, cu exact aceleași permisiuni ca cea veche. Apoi verificați propagarea acesteia cu GET /auth/api-keys/{newKeyId}/propagation—o cheie proaspăt creată nu este cunoscută instantaneu în întreaga infrastructură, iar o implementare prea timpurie produce erori confuze. În continuare, implementați noua cheie pe backend-urile dumneavoastră și testați dacă apelurile funcționează efectiv cu aceasta, nu doar că implementarea s-a finalizat fără erori. Doar după ce aveți această confirmare ar trebui să dezactivați vechea cheie sau să așteptați până la expirarea acesteia, înainte de a o șterge permanent cu DELETE /auth/api-keys/{oldKeyId}.

Această abordare „cheie nouă, apoi ștergere“ vă oferă o perioadă de suprapunere în care ambele chei coexistă: dacă implementarea eșuează pe un server, nimic nu se strică. Rotația pe loc rămâne disponibilă dacă doriți să păstrați același ID de cheie:

curl -X POST \
  "https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

În acest caz, planificați actualizarea backend-urilor dumneavoastră imediat, deoarece vechea cheie devine inutilizabilă în momentul în care apelul se finalizează.

Ciclul complet de viață al unei chei

O cheie bine gestionată are o poveste în patru acte. La creare, prin POST /auth/teams/{teamId}/api-keys, definiți numele său, ACL-urile sale și—acesta este obiceiul de consolidat—data sa de expirare:

{
  "name": "prod-chat-service",
  "acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
  "expireTime": "2026-12-31T23:59:59Z"
}

O cheie fără expireTime este o cheie care va trăi la infinit dacă nimeni nu se gândește la ea; o cheie cu expirare forțează echipa dumneavoastră să pună problema reînnoirii la o dată fixă. Urmează monitorizarea: GET /v1/api-key vă indică starea cheii (api_key_blocked, api_key_disabled), iar consola xAI expune utilizarea și anomaliile. Pentru modificări la jumătatea vieții—redenumire, ajustare ACL-uri, strângerea limitelor de rată, împingerea datei de expirare—utilizați PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. În final, ștergerea, DELETE /auth/api-keys/{apiKeyId}, este permanentă și ireversibilă: orice aplicație care utilizează această cheie se oprește instantaneu. Înainte de a șterge, asigurați-vă că niciun serviciu uitat—un cron lunar, un script de raportare—nu mai depinde de ea.

Ce strategie de rotație ar trebui să adoptați?

Frecvența corectă depinde de sensibilitatea mediului dumneavoastră. Rotația lunară este obligatorie în contexte highly sensibile precum finanțele sau sănătatea, unde fereastra de expunere trebuie să rămână minimă. Rotația trimestrială se potrivește mediilor profesionale standard: suficient de frecventă pentru a fi eficientă, suficient de spațiată pentru a nu împovăra echipele. Rotația anuală, cuplată cu o dată de expirare definită, este minimul acceptabil—sub acest prag, politica dumneavoastră de rotație nu este cu adevărat o politică. În toate cazurile, automatizarea printr-un script programat vă scutește de dependența de memoria unui administrator.

Rotația declanșată de evenimente se adaugă acestui program, fiind activată de circumstanțe mai degrabă decât de date. Cel mai adesea o veți declanșa la plecarea unui angajat care a avut acces la chei: chiar dacă separarea este cordială, cheia pe care o cunoștea trebuie rotită în aceeași zi—aceasta este o regulă de igienă de securitate, nu un semn de neîncredere. Procedați la fel în caz de compromitere suspectată, un incident de securitate în infrastructura dumneavoastră sau o schimbare de furnizor care a avut acces la sistemele dumneavoastră.

Douăzeci de minute pentru a recâștiga controlul inventarului dumneavoastră

Cel mai bun moment pentru a descoperi starea reală a cheilor dumneavoastră nu este ziua auditului. Așadar, listați acum toate cheile dumneavoastră cu GET /auth/teams/{teamId}/api-keys și identificați-le pe cele fără expirare, pentru a adăuga un expireTime. Pentru fiecare, întrebați-vă dacă ACL-urile sale corespund minimului strict necesar aplicației care le utilizează; o cheie creată pentru un prototip și reciclată în producție poartă aproape întotdeauna prea multe drepturi.

Apoi ștergeți cheile neutilizate, deoarece fiecare cheie activă este un vector potențial de atac, iar o cheie de care nimeni nu-și amintește este cea mai rea dintre toate: nimeni nu va observa utilizarea sa anormală. Terminați prin a documenta cine are acces la care cheie și de ce. Acest document, mai mult decât cheile în sine, este ceea ce veți scoate la următorul audit.

Puncte cheie

  • Endpoint-ul POST /auth/api-keys/{id}/rotate invalidează vechea cheie permanent, fără perioadă de grație
  • În producție, preferați crearea unei chei noi, apoi ștergerea celei vechi pentru a evita orice întrerupere
  • Setați întotdeauna o dată de expirare pentru cheile dumneavoastră
  • Automatizați rotația cu un script programat (lunar, trimestrial sau anual, în funcție de sensibilitate)
  • Declanșați rotația imediată la orice schimbare de personal sau incident de securitate