Списък и модифициране на вашите ключове
На тази страница
Инвентаризация на вашите API ключове
С времето екипът Ви натрупва API ключове за различни среди, проекти и членове на екипа. Management API Ви позволява да изброите всички активни ключове, да ги филтрирате по права и да променяте настройките им, без да се налага да ги преиздавате.
Списък с ключове
Тази крайна точка е отправната точка за всеки одит на достъпа и често именно тук откривате реалния инвентар: ключове, създадени за тест преди осем месеца, ключ на името на бивш служител, два производствени ключа, без никой да знае кой от тях се използва. Правете списък, преди да създавате каквото и да е ново – ключът, от който се нуждаете, може вече да съществува.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Параметри на заявката
- pageSize: брой ключове на страница (по подразбиране се връщат всички ключове)
- paginationToken: токен за извличане на следващата страница, ако броят на ключовете надвишава размера на страницата
- aclFilters: филтриране на ключовете по конкретни права
Филтриране по ACL
Можете да извлечете само ключовете с определено ниво на достъп:
# Изброяване само на ключове с достъп до чат
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Това филтриране прави одита управляем дори при повече от дузина ключове. На практика възникват два въпроса, на които се отговаря с една единствена заявка: кой може да извиква най-скъпия модел и кои ключове все още притежават уайлдкард (wildcard). Вторият е най-полезният – забравен уайлдкард в производствена среда е най-честата грешка в конфигурацията и най-тихата.
Странициране
За екипи с много ключове използвайте странициране:
# Първа страница от 10 ключа
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Следваща страница с получения токен
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Модифициране на съществуващ ключ
Модифицирането, вместо преиздаването, не е просто удобство: тайният ключ остава същият, така че не е необходимо ново разполагане (deployment). Това Ви позволява да коригирате лимити или да ограничите правата без прекъсване на услугата – а в случай на съмнение, да намалите правата на ключ за секунди, докато подготвяте неговата ротация.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v3",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 30,
"qpm": 1000,
"tpm": 3000000
}'
Какво можете да модифицирате
- name: преименуване на ключа, за да отразява промяна в употребата
- acls: добавяне или премахване на права (крайни точки, модели)
- qps / qpm / tpm: коригиране на лимитите за честота
- expireTime: удължаване или съкращаване на периода на валидност
Какво НЕ можете да модифицирате
- Идентификаторът на ключа (
api_key_id) остава фиксиран - Тайният ключ не се променя по време на модификация (използвайте ротация за това)
- Екипът собственик не може да бъде прехвърлен
Проверка на разпространението
Ето детайлът, който обяснява половината от „бъговете“, докладвани след модификация на ключ: промяната не е мигновена на всички сървъри. В новоиздаден ключ може да върне 401 за няколко момента, разширен ACL може все още да не е активен – и Вие търсите грешката в собствения си код, когато просто е трябвало да изчакате. Крайната точка за разпространение съществува именно за да премахне това съмнение:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Тази крайна точка връща статуса на разпространение на ключа. Изчакайте разпространението да приключи, преди да използвате ключа в производствена среда, особено след модифициране на ACL.
Чести сценарии
Надграждане на ключ за разработка до производствен
Преминаването към производствена среда е най-честият сценарий за модификация, а рефлексът да се създаде нов ключ при този случай е скъп: трябва да го разположите навсякъде, да актуализирате хранилищата за тайни (vaults), а старият остава да съществува за неопределено време. Повишаването на лимитите на съществуващия ключ избягва всичко това.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-chatbot",
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}'
Ограничаване на ключ с подозрение за компрометиране
В случай на съмнение, редът на операциите има значение. Първо ограничете – празни ACL, нулеви лимити на честотата – това спира изтичането с една заявка, без да причинява необратими щети. Ротацията идва по-късно, офлайн, след като сте идентифицирали къде е използван ключът. Обратният ред Ви оставя с спряна производствена среда и разследване, което трябва да проведете под напрежение.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"acls": [],
"qps": 0,
"qpm": 0
}'
Ключови изводи
GET /auth/teams/{teamId}/api-keysизброява всички ключове със странициране и филтриране по ACLPUT /auth/api-keys/{apiKeyId}модифицира параметрите, без да променя тайния ключGET /auth/api-keys/{apiKeyId}/propagationпроверява дали промените са влезли в сила- Използвайте филтриране по ACL, за да одитирате редовно достъпа на екипа си
- След всяка модификация проверявайте разпространението, преди да използвате ключа в производствена среда