Премини към основното съдържание
Български— Изберете език
Меню

Списък и модифициране на вашите ключове

Урок 3 от 14 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Инвентаризация на вашите API ключове
  2. Списък с ключове
  3. Модифициране на съществуващ ключ
  4. Проверка на разпространението
  5. Чести сценарии
  6. Ключови изводи

Инвентаризация на вашите 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 изброява всички ключове със странициране и филтриране по ACL
  • PUT /auth/api-keys/{apiKeyId} модифицира параметрите, без да променя тайния ключ
  • GET /auth/api-keys/{apiKeyId}/propagation проверява дали промените са влезли в сила
  • Използвайте филтриране по ACL, за да одитирате редовно достъпа на екипа си
  • След всяка модификация проверявайте разпространението, преди да използвате ключа в производствена среда