Avainten kierrätys ja elinkaari
Tällä sivulla
Miksi avainten kierrätys on välttämätöntä
Koulutustilaisuuksissa kuulee usein väitteen: “Avaintani ei ole koskaan vuotanut, miksi vaihtaisin sitä?” Vastaus tiivistyy yhteen sanaan: epävarmuus. Et voi koskaan todistaa, ettei avainta ole paljastettu – palvelimelle unohtunut laaja lokitiedosto, tukipyyntöön liitetty kuvakaappaus tai kuusi kuukautta sitten kompromissoitunut kehittäjän työasema. Säännöllinen kierrätys muuttaa tämän epävarmuuden hallituksi riskiksi: vaikka avain olisi kopioitu tietämättäsi, se lakkaa toimimasta seuraavassa kierrätyksessä. Tämä on täsmälleen sama päättelyketju, jota SOC 2 -tilintarkastajat käyttävät; he odottavat dokumentoitua kierrätyskäytäntöä. Tätä kutsutaan ajallisen hyökkäyspinnan pienentämiseksi: mitä kauemmin avain on voimassa, sitä pidempi on hiljaisen kompromissoinnin hyväksikäyttöikkuna.
xAI:n hallinta-API on suunniteltu tekemään tästä käytännöstä vaivatonta: se tarjoaa erillisen päätepisteen, jonka avulla voit kierrättää avaimen uudelleenkirjoittamatta asetuksiasi.
Kierrätys hallinta-API:n kautta
Kierrätyspäätepiste on suoraviivainen:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Varmista, että ymmärrät tämän kutsun vaikutukset ennen käyttöä: se luo uuden salaisen avaimen olemassa olevalle tunnukselle ja mitätöi vanhan pysyvästi säilyttäen kuitenkin avaimeseen liitetyt käyttöoikeusluettelot (ACL), nopeusrajoitukset ja määritykset. Mikä yllättää tiimit ensimmäisellä kerralla, on se, että muutos on välitön ja peruuttamaton. Jos tuotantoympäristön backend käyttää tätä avainta kierrätyksen käynnistyshetkellä, se alkaa vastaanottaa todennusvirheitä sekunneissa. Armeliaisuusaikaa ei ole, eikä paluuta edelliseen tilaan ole mahdollista.
Siksi tuotannossa suositellaan yleensä kaksivaiheista menettelyä katkosten välttämiseksi. Luo ensin uusi avain komennolla POST /auth/teams/{teamId}/api-keys täsmälleen samoilla oikeuksilla kuin vanhalla avaimella. Varmista sen leviäminen komennolla GET /auth/api-keys/{newKeyId}/propagation – vastaluotu avain ei ole heti tiedossa koko infrastruktuurissa, ja liian aikainen käyttöönotto aiheuttaa hämmentäviä virheitä. Seuraavaksi ota uusi avain käyttöön backendeissäsi ja testaa, että pyynnöt todella toimivat sillä, äläkä vain sitä, että käyttöönotto päättyi ilman virheitä. Vasta kun olet saanut tämän vahvistuksen, poista vanha avain käytöstä tai anna sen vanhentua, ennen kuin poistat sen pysyvästi komennolla DELETE /auth/api-keys/{oldKeyId}.
Tämä “uusi avain, sitten poisto” -lähestymistapa luo päällekkäisjakson, jolloin molemmat avaimet ovat voimassa: jos käyttöönotto epäonnistuu yhdellä palvelimella, mikään ei hajoa. Paikallaan suoritettava kierrätys on edelleen käytettävissä, jos haluat säilyttää saman avaintunnuksen:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Tässä tapauksessa suunnittele backendiesi päivittäminen välittömästi, sillä vanha avain lakkaa toimimasta heti kutsun valmistuttua.
Avaimen koko elinkaari
Hyvin hallitulla avaimella on nelinäytöksinen tarina. Luontivaiheessa, komennolla POST /auth/teams/{teamId}/api-keys, määrität sen nimen, käyttöoikeusluettelonsa (ACL) ja – tämä on tapa, joka on juurrutettava – sen vanhentumispäivämäärän:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Avain, jolta puuttuu expireTime, on avain, joka elää ikuisesti, ellei kukaan muista sitä; avain, jolla on vanhentumispäivä, pakottaa tiimisi kysymään uusimisesta tiettynä päivämääränä. Seuraavaksi tulee seuranta: GET /v1/api-key kertoo avaimen tilan (api_key_blocked, api_key_disabled), ja xAI-konsoli näyttää käytön ja poikkeamat. Elinkaaren keskivaiheen muutoksiin – nimeäminen uudelleen, ACL-säädöt, nopeusrajoitusten kiristäminen, vanhentumisen lykkääminen – käytä komentoa PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Lopuksi poisto, DELETE /auth/api-keys/{apiKeyId}, on pysyvä ja peruuttamaton: mikä tahansa tätä avainta käyttävä sovellus lakkaa toimimasta välittömästi. Ennen poistamista varmista, ettei mikään unohdettu palvelu – kuukausittainen cron-tehtävä, raportointiskripti – ole edelleen riippuvainen siitä.
Minkä kierrätysstrategian sinun tulisi omaksua?
Oikea tahti riippuu ympäristösi herkkyystasosta. Kuukausittainen kierrätys on pakollinen erittäin herkissä konteksteissa, kuten rahoituksessa tai terveydenhuollossa, joissa altistumisikkunan on pysyttävä minimaalisena. Neljännesvuosittainen kierrätys sopii tavallisiin ammattimaisiin ympäristöihin: se on tarpeeksi usein ollakseen tehokas, mutta tarpeeksi harvoin, ettei se kuormita tiimejä. Vuosittainen kierrätys yhdistettynä määriteltyyn vanhentumispäivään on hyväksyttävä minimi – sen alapuolella kierrätyskäytäntösi ei ole oikeastaan käytäntö. Kaikissa tapauksissa automatisointi ajoitetun skriptin avulla vapauttaa sinut luottamasta järjestelmänvalvojan muistiin.
Tapahtumalähtöinen kierrätys täydentää tätä aikataulua; se laukaistaan olosuhteiden eikä päivämäärän perusteella. Laukaiset sen useimmiten sellaisen työntekijän lähdön yhteydessä, jolla oli pääsy avaimiin: vaikka ero olisi sovinnollinen, hänen tietämänsä avain on kierrätettävä samana päivänä – tämä on tietoturvahygienian sääntö, ei epäluottamuksen merkki. Tee samoin epäillyn kompromissoinnin, infrastruktuurisi tietoturvatapahtuman tai järjestelmiisi pääsyn omaavan toimittajan vaihtumisen yhteydessä.
Kaksikymmentä minuuttia inventaarion haltuunottoon
Paras aika selvittää avaintesi todellinen tila ei ole tilintarkastuspäivä. Listaa siis kaikki avaimesi nyt komennolla GET /auth/teams/{teamId}/api-keys ja tunnista ne, joilta puuttuu vanhentumispäivä, lisätäksesi niille expireTime. Kysy itseltäsi jokaisen kohdalla, vastaavatko sen käyttöoikeusluettelot (ACL) sitä ehdotonta minimiä, jota sitä käyttävä sovellus vaatii; prototyyppiä varten luotu ja tuotantoon kierrätetty avain kantaa lähes aina liian paljon oikeuksia.
Poista sen jälkeen käyttämättömät avaimet, sillä jokainen aktiivinen avain on potentiaalinen hyökkäysvektori, ja avain, jota kukaan ei muista, on pahin kaikista: kukaan ei huomaa sen epänormaalia käyttöä. Viimeistele dokumentoimalla, kenellä on pääsy mihinkin avaimeen ja miksi. Tämä asiakirja on se, jonka otat esiin seuraavassa tilintarkastuksessa, enemmän kuin itse avaimet.
Keskeiset asiat
- Päätepiste
POST /auth/api-keys/{id}/rotatemitätöi vanhan avaimen pysyvästi ilman armeliaisuusaikaa - Suosi tuotannossa uuden avaimen luomista ja vanhan poistamista katkosten välttämiseksi
- Aseta avaimillesi aina vanhentumispäivä
- Automatisoi kierrätys ajoitetulla skriptillä (kuukausittain, neljännesvuosittain tai vuosittain herkkyyden mukaan)
- Käynnistä välitön kierrätys kaikissa henkilöstömuutoksissa tai tietoturvatapahtumissa