Ротация на ключове и жизнен цикъл
На тази страница
Защо ротацията на ключове е от съществено значение
Често възражение по време на обученията е: „Моят ключ никога не е изтичал, защо да го сменям?“ Отговорът се свежда до една дума: несигурност. Никога не можете да докажете, че даден ключ не е бил компрометиран – забравен подробен лог на сървър, скрийншот, споделен в билет за поддръжка, или компрометирана работна станция на разработчик от преди шест месеца. Редовната ротация превръща тази несигурност в ограничен риск: дори ако ключът е бил копиран без Вашето знание, той ще спре да работи при следващата ротация. Това е точно логиката, която одиторите за SOC 2 използват; те очакват документирана политика за ротация. Това наричаме намаляване на времевата повърхност за атака: колкото по-дълго живее един ключ, толкова по-дълъг е прозорецът за експлоатация при тихо компрометиране.
Управленското API на xAI е проектирано така, че тази практика да бъде безболезнена: то предоставя специализиран крайна точка, която Ви позволява да ротирате ключ, без да презаписвате конфигурациите си.
Ротация чрез Управленското API
Крайната точка за ротация е проста:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Уверете се, че разбирате какво прави това извикване, преди да го използвате: то генерира нов секретен ключ за съществуващия ID и永久性 анулира стария, като същевременно запазва ACL списъците, лимитите за честота и конфигурациите, прикрепени към ключа. Нещото, което изненадва екипите за първи път, е, че промяната е незабавна и необратима. Ако Вашият производствен бекенд използва този ключ, когато задействате ротацията, той ще започне да получава грешки при удостоверяване в рамките на секунди. Няма гратисен период, няма начин за връщане назад.
Ето защо в производствена среда обикновено предпочитате двуетапна процедура, за да избегнете всякакво прекъсване. Първо, създайте нов ключ чрез POST /auth/teams/{teamId}/api-keys с точно същите права като стария. След това проверете разпространението му с GET /auth/api-keys/{newKeyId}/propagation – новосъздаден ключ не е мигновено известен в цялата инфраструктура и твърде ранното му внедряване води до объркващи грешки. След това внедрете новия ключ във Вашите бекенд системи и тествайте дали извикванията действително работят с него, а не просто дали внедряването е приключило без грешки. Едва след като имате това потвърждение, трябва да деактивирате стария ключ или да изчакате той да достигне срока си на валидност, преди да го изтриете окончателно с DELETE /auth/api-keys/{oldKeyId}.
Този подход „нов ключ, след това изтриване“ Ви осигурява период на припокриване, в който двата ключа съществуват едновременно: ако внедряването се провали на един сървър, нищо не се прекъсва. Ротацията на място остава налична, ако искате да запазите същия ID на ключа:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
В този случай планирайте да актуализирате бекенд системите си незабавно, тъй като старият ключ умира в момента, в който извикването приключи.
Пълният жизнен цикъл на един ключ
Един добре управляван ключ има история в четири действия. При създаването, чрез POST /auth/teams/{teamId}/api-keys, Вие дефинирате неговото име, неговите ACL списъци и – това е навикът, който трябва да затвърдите – неговата дата на изтичане:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Ключ без expireTime е ключ, който ще живее вечно, ако никой не се замисли за него; ключ с дата на изтичане принуждава Вашия екип да постави въпроса за подновяване на фиксирана дата. Следва мониторингът: GET /v1/api-key Ви показва статуса на ключа (api_key_blocked, api_key_disabled), а конзолата на xAI предоставя данни за използването и аномалиите. За модификации по средата на жизнения цикъл – преименуване, коригиране на ACL списъци, затягане на лимитите за честота, отлагане на изтичането – използвайте PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Накрая, изтриването чрез DELETE /auth/api-keys/{apiKeyId} е окончателно и необратимо: всяко приложение, използващо този ключ, спира да работи мигновено. Преди да изтриете, се уверете, че няма забравен сервис – месечен cron, скрипт за отчети – който все още зависи от него.
Каква стратегия за ротация да приемете?
Правилната честота зависи от чувствителността на Вашата среда. Месечната ротация е задължителна във високо чувствителни контексти като финансите или здравеопазването, където прозорецът на експозиция трябва да остане минимален. Тримесечната ротация е подходяща за стандартни професионални среди: достатъчно честа, за да бъде ефективна, и достатъчно разредена, за да не натоварва екипите. Годишната ротация, съчетана с определена дата на изтичане, е приемливият минимум – под това Вашата политика за ротация всъщност не е политика. Във всички случаи автоматизацията чрез планиран скрипт Ви спасява от зависимостта от паметта на администратор.
Към този график се добавя и ротацията, движена от събития, задействана от обстоятелства, а не от дата. Най-често ще я задействате при напускането на служител, който е имал достъп до ключове: дори ако разделянето е приятелско, ключът, който той е познавал, трябва да бъде ротиран същия ден – това е правило за хигиена на сигурността, а не знак за недоверие. Правете същото в случай на подозрение за компрометиране, инцидент със сигурността във Вашата инфраструктура или смяна на доставчик, който е имал достъп до Вашите системи.
Двадесет минути, за да си върнете контрола над инвентара си
Най-доброто време да откриете реалното състояние на Вашите ключове не е денят на одита. Затова избройте всички свои ключове сега с GET /auth/teams/{teamId}/api-keys и идентифицирайте онези без дата на изтичане, за да добавите expireTime. За всеки от тях се запитайте дали неговите ACL списъци съответстват на строгия минимум, изискван от приложението, което го използва; ключ, създаден за прототип и рециклиран в производство, почти винаги носи твърде много права.
След това изтрийте неизползваните ключове, защото всеки активен ключ е потенциален вектор за атака, а ключ, за който никой не помни, е най-лошият от всички: никой няма да забележи неговата необичайна употреба. Завършете, като документирате кой има достъп до кой ключ и защо. Този документ, повече от самите ключове, е това, което ще извадите при следващия одит.
Ключови изводи
- Крайната точка
POST /auth/api-keys/{id}/rotateанулира стария ключ окончателно, без гратисен период - В производствена среда предпочитайте създаването на нов ключ, след което изтриването на стария, за да избегнете всякакво прекъсване
- Винаги задавайте дата на изтичане на Вашите ключове
- Автоматизирайте ротацията с планиран скрипт (месечно, тримесечно или годишно в зависимост от чувствителността)
- Задействайте незабавна ротация при всяка промяна в персонала или инцидент със сигурността