Rotace klíčů a jejich životní cyklus
Na této stránce
Proč je rotace klíčů nezbytná
Během školení se často ozývá námitka: „Můj klíč nikdy neunikl, proč ho měnit?“ Odpověď se vejde do jednoho slova: nejistota. Nikdy nemůžeš s jistotou prokázat, že klíč nebyl odhalen – zapomenutý podrobný log na serveru, screenshot sdílený v ticketu podpory nebo kompromitovaná pracovní stanice vývojáře před šesti měsíci. Pravidelná rotace mění tuto nejistotu na ohraničené riziko: i když byl klíč zkopírován bez tvého vědomí, při příští rotaci přestane fungovat. Přesně tak uvažují auditoři SOC 2; očekávají zdokumentovanou politiku rotace. Říkáme tomu snižování časového útočného povrchu: čím déle klíč žije, tím delší je okno pro zneužití při tichém kompromitování.
Management API od xAI je navrženo tak, aby byla tato praxe bezbolestná: poskytuje vyhrazený endpoint, který ti umožní rotovat klíč bez přepisování konfigurací.
Rotace prostřednictvím Management API
Endpoint pro rotaci je přímočarý:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Než tento požadavek použiješ, ujisti se, že chápeš, co dělá: vygeneruje nový tajný klíč pro existující ID a trvale zneplatní ten starý, přičemž zachová ACL, limity rychlosti a konfigurace připojené ke klíči. Co týmy poprvé zaskočí, je okamžitost a nevratnost změny. Pokud tvé produkční backendy tento klíč používají v momentě, kdy rotaci spustíš, začnou během několika sekund dostávat chyby autentizace. Neexistuje žádná lhůta shovívavosti ani možnost návratu.
Proto v produkci obvykle upřednostňuješ dvoustupňový postup, abys předešel jakémukoli výpadku. Nejprve vytvoř nový klíč pomocí POST /auth/teams/{teamId}/api-keys s přesně stejnými oprávněními jako ten starý. Poté ověř jeho propagaci pomocí GET /auth/api-keys/{newKeyId}/propagation – nově vytvořený klíč není okamžitě známý v celé infrastruktuře a příliš brzké nasazení způsobuje matoucí chyby. Dále nasaď nový klíč na své backendy a otestuj, že s ním volání skutečně fungují, nejen že nasazení proběhlo bez chyb. Teprve až získáš toto potvrzení, měl bys starý klíč deaktivovat nebo nechat dojít k jeho vypršení, než jej trvale smažeš pomocí DELETE /auth/api-keys/{oldKeyId}.
Tento přístup „nejprve nový klíč, pak smazat“ ti dává překrývající se období, kdy oba klíče koexistují: pokud nasazení na jednom serveru selže, nic se nerozbije. Rotace na místě zůstává k dispozici, pokud chceš zachovat stejné ID klíče:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
V tomto případě si naplánuj okamžitou aktualizaci backendů, protože starý klíč zemře v okamžiku dokončení volání.
Kompletní životní cyklus klíče
Dobře spravovaný klíč má příběh o čtyřech dějstvích. Při vytvoření přes `POST /auth/teams/{teamId}/api-keys} definuješ jeho název, jeho ACL a – toto je zvyk, který si musíš osvojit – datum vypršení platnosti:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Klíč bez expireTime je klíč, který bude žít navždy, pokud si na něj nikdo nevzpomene; klíč s datem vypršení nutí tvůj tým položit si otázku obnovy v pevně stanovený termín. Následuje monitorování: GET /v1/api-key ti sdělí stav klíče (api_key_blocked, api_key_disabled) a konzole xAI zobrazuje využití a anomálie. Pro úpravy v průběhu života – přejmenování, úpravu ACL, zpřísnění limitů rychlosti, prodloužení vypršení – použij PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Nakonec, smazání pomocí DELETE /auth/api-keys/{apiKeyId} je trvalé a nevratné: jakákoli aplikace používající tento klíč okamžitě přestane fungovat. Před smazáním se ujisti, že na něm nezávisí žádná zapomenutá služba – měsíční cron, skript pro reportování.
Jakou strategii rotace bys měl přijmout?
Správná frekvence závisí na citlivosti tvého prostředí. Měsíční rotace je povinná ve vysoce citlivých kontextech, jako jsou finance nebo zdravotnictví, kde musí být okno expozice minimální. Čtvrtletní rotace vyhovuje standardním profesionálním prostředími: dostatečně častá na to, aby byla účinná, dostatečně rozložená, aby nezatěžovala týmy. Roční rotace spojená s definovaným datem vypršení je přijatelné minimum – pod touto hranicí tvá politika rotace ve skutečnosti politikou není. Ve všech případech tě automatizace pomocí naplánovaného skriptu ušetří závislosti na paměti administrátora.
K tomuto harmonogramu přidává rotaci řízenou událostmi, která je spuštěna okolnostmi nikoli datem. Nejčastěji ji spustíš při odchodu zaměstnance, který měl přístup ke klíčům: i když je rozchod přátelský, klíč, který znal, se musí rotovat ještě týž den – jde o pravidlo bezpečnostní hygieny, nikoli o známku nedůvěry. Totéž udělej v případě podezření na kompromitaci, bezpečnostního incidentu ve tvé infrastruktuře nebo změny dodavatele, který měl přístup k tvým systémům.
Dvacet minut k získání kontroly nad inventářem
Nejlepší čas zjistit skutečný stav tvých klíčů není den auditu. Proto si nyní vypiš všechny své klíče pomocí GET /auth/teams/{teamId}/api-keys a identifikuj ty bez data vypršení, abys jim přidal expireTime. U každého z nich se zeptej sám sebe, zda jeho ACL odpovídají přísnému minimu požadovanému aplikací, která jej používá; klíč vytvořený pro prototyp a recyklovaný do produkce téměř vždy nese příliš mnoho práv.
Poté smaž nepoužívané klíče, protože každý aktivní klíč je potenciálním útočným vektorem a klíč, na který si nikdo nepamatuje, je ze všech nejhorší: nikdo si nevšimne jeho abnormálního využití. Nakonec zdokumentuj, kdo má přístup ke kterému klíči a proč. Tento dokument, více než samotné klíče, je to, co vytáhneš při příštím auditu.
Klíčové poznatky
- Endpoint
POST /auth/api-keys/{id}/rotatetrvale zneplatní starý klíč bez jakékoli lhůty shovívavosti - V produkci upřednostni vytvoření nového klíče a následné smazání starého, abys předešel jakémukoli výpadku
- Vždy nastav klíčům datum vypršení platnosti
- Automatizuj rotaci pomocí naplánovaného skriptu (měsíčně, čtvrtletně nebo ročně podle míry citlivosti)
- Okamžitě spusť rotaci při jakékoli změně personálu nebo bezpečnostním incidentu