Rotacija ključeva i životni ciklus
Na ovoj stranici
Zašto je rotacija ključeva ključna
Čest prigovor na treninzima glasi: „Moj ključ nikada nije procurio, zašto bih ga mijenjao?“ Odgovod se svodi na jednu riječ: neizvjesnost. Nikada ne možeš dokazati da ključ nije bio izložen – zaboravljeni opširni zapisnik na poslužitelju, snimka zaslona podijeljena u zahtjevu za podršku ili kompromitirana radna stanica programera od prije šest mjeseci. Redovita rotacija tu neizvjesnost pretvara u ograničen rizik: čak i da je ključ kopiran bez tvog znanja, prestat će raditi pri sljedećoj rotaciji. Točno je to obrazloženje koje koriste revizori za SOC 2; oni očekuju dokumentiranu politiku rotacije. To nazivamo smanjenjem vremenske površine napada: što ključ duže živi, to je veći prozor za iskorištavanje tihe kompromitacije.
xAI-jev upravljački API dizajniran je tako da ova praksa bude bezbolna: pruža namjensku krajnju točku koja ti omogućuje rotaciju ključa bez prepisivanja konfiguracija.
Rotacija putem upravljačkog API-ja
Krajnja točka za rotaciju jednostavna je:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Prije korištenja ovog poziva moraš razumjeti što on radi: generira novi tajni ključ za postojeći ID i trajno poništava stari, zadržavajući pritom ACL-ove, ograničenja stope i konfiguracije vezane uz ključ. Ono što timove prvi put iznenadi jest da je promjena trenutna i nepovratna. Ako tvoje produkcijsko pozadinsko sustav koristi ovaj ključ kada pokreneš rotaciju, unutar nekoliko sekundi počet će primati pogreške autentifikacije. Nema razdoblja milosti, nema načina za povratak na staro.
Zato u produkcijskom okruženju općenito preferiraš dvokorakni postupak kako bi izbjegao bilo kakav prekid. Prvo stvori novi ključ putem POST /auth/teams/{teamId}/api-keys, s točno istim dopuštenjima kao i stari. Zatim provjeri njegovu propagaciju s GET /auth/api-keys/{newKeyId}/propagation – svježe stvoreni ključ nije trenutno poznat cijeloj infrastrukturi, a prerano uvođenje uzrokuje zbunjujuće pogreške. Dalje, uvedi novi ključ u svoje pozadinske sustave i testiraj rade li pozivi stvarno s njim, a ne samo je li uvođenje završilo bez pogrešaka. Tek kada dobiješ tu potvrdu, onemogući stari ključ ili pričekaj da istekne, prije nego ga trajno obrišeš s DELETE /auth/api-keys/{oldKeyId}.
Ovaj pristup „prvo novi ključ, zatim brisanje“ daje ti razdoblje preklapanja u kojem oba ključa postoje istovremeno: ako uvođenje na jednom poslužitelju ne uspije, ništa se ne kvari. Rotacija na mjestu i dalje je dostupna ako želiš zadržati isti ID ključa:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
U ovom slučaju planiraj trenutno ažuriranje svojih pozadinskih sustava jer stari ključ umire onog trena kada poziv završi.
Potpuni životni ciklus ključa
Dobro upravljani ključ ima priču u četiri čina. Pri stvaranju, putem POST /auth/teams/{teamId}/api-keys, definiraš njegovo ime, ACL-ove i – ovo je navika koju trebaš učvrstiti – datum isteka:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Ključ bez expireTime je ključ koji će živjeti zauvijek ako se nitko ne sjeti njega; ključ s datumom isteka prisiljava tvoj tim da postavi pitanje obnove na fiksni datum. Slijedi praćenje: GET /v1/api-key govori ti status ključa (api_key_blocked, api_key_disabled), a xAI konzola prikazuje korištenje i anomalije. Za modifikacije tijekom životnog vijeka – preimenovanje, prilagodbu ACL-ova, zaoštravanje ograničenja stope, odgodu isteka – koristi PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Konačno, brisanje, DELETE /auth/api-keys/{apiKeyId}, trajno je i nepovratno: svaka aplikacija koja koristi ovaj ključ trenutno prestaje raditi. Prije brisanja osiguraj da nijedna zaboravljena usluga – mjesečni cron, skripta za izvješćivanje – više ne ovisi o njemu.
Koju strategiju rotacije trebaš usvojiti?
Prava učestalost ovisi o osjetljivosti tvog okruženja. Mjesečna rotacija obavezna je u visoko osjetljivim kontekstima poput financija ili zdravstva, gdje prozor izloženosti mora ostati minimalan. Tromjesečna rotacija odgovara standardnim profesionalnim okruženjima: dovoljno česta da bude učinkovita, a dovoljno razmaknuta da ne opterećuje timove. Godišnja rotacija, uz definirani datum isteka, prihvatljiv je minimum – ispod toga tvoja politika rotacije zapravo i nije politika. U svim slučajevima, automatizacija putem planirane skripte štedi te oslanjanja na pamćenje administratora.
Rotacija vođena događajima nadopunjuje ovaj raspored, pokrenuta okolnostima umjesto datumom. Najčešće ćeš je pokrenuti pri odlasku zaposlenika koji je imao pristup ključevima: čak i ako je rastanak srdačan, ključ koji je ta osoba poznavala mora se rotirati istog dana – to je pravilo sigurnosne higijene, a ne znak nepovjerenja. Učini isto u slučaju sumnje na kompromitaciju, sigurnosnog incidenta u tvojoj infrastrukturi ili promjene dobavljača koji je imao pristup tvojim sustavima.
Dvadeset minuta za ponovno preuzimanje kontrole nad inventarom
Najbolje vrijeme za otkrivanje stvarnog stanja tvojih ključeva nije dan revizije. Zato sada izlistaj sve svoje ključeve s GET /auth/teams/{teamId}/api-keys i identificiraj one bez datuma isteka kako bi im dodao expireTime. Za svaki od njih zapitaj se odgovaraju li njegovi ACL-ovi strogom minimumu koji zahtijeva aplikacija koja ga koristi; ključ stvoren za prototip i recikliran u produkciju gotovo uvijek nosi previše prava.
Zatim obriši nekorištene ključeve jer je svaki aktivni ključ potencijalni vektor napada, a ključ kojeg se nitko ne sjeća najgori je od svih: nitko neće primijetiti njegovu abnormalnu upotrebu. Završi dokumentiranjem tko ima pristup kojem ključu i zašto. Taj je dokument, više od samih ključeva, ono što ćeš izvući na sljedećoj reviziji.
Ključne točke
- Krajnja točka
POST /auth/api-keys/{id}/rotatetrajno poništava stari ključ, bez razdoblja milosti - U produkciji preferiraj stvaranje novog ključa, a zatim brisanje starog kako bi izbjegao bilo kakav prekid
- Uvijek postavi datum isteka na svoje ključeve
- Automatiziraj rotaciju planiranom skriptom (mjesečno, tromjesečno ili godišnje, ovisno o osjetljivosti)
- Pokreni trenutnu rotaciju pri svakoj promjeni osoblja ili sigurnosnom incidentu