Валидиране на управленския ключ
На тази страница
Проверка на целостта на вашите ключове
Валидирането на управленския ключ е първата линия на защита на вашата API инфраструктура. Преди всяка критична операция – внедряване, ротация, промени във фактурирането – уверете се, че ключът ви е валиден и че разрешенията му са коректни.
Крайна точка за валидиране
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Отговорът потвърждава, че ключът е активен, и връща екипа, разрешенията и свързаните дати. Не подценявайте датата на изтичане: това е единствената информация, която ви позволява да предвидите прекъсване, вместо да го претърпите, тъй като изтекъл ключ не ви предупреждава – той просто връща код 401 при първото последващо извикване.
Случаи на грешки
- 401 Unauthorized: Ключът е невалиден, изтекъл или е изтрит
- 403 Forbidden: Ключът е валиден, но няма необходимите разрешения за поисканата операция
Интегриране във вашите скриптове
Проверка при стартиране
Валидирането при стартиране премества отказа там, където той струва най-малко. Без тази проверка невалиден ключ се проявява при първото полезно извикване – тоест по средата на обработката, понякога след като няколко стъпки вече са изпълнени. С нея скриптът спира за три секунди със съобщение, което посочва причината.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Проверява дали управленският ключ е валиден."""
try:
response = requests.get(
f"{MANAGEMENT_API}/auth/management-keys/validation",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
timeout=10
)
if response.status_code == 200:
print("Управленският ключ е валиден")
return True
elif response.status_code == 401:
print("ГРЕШКА: Управленският ключ е невалиден или изтекъл")
return False
else:
print(f"ГРЕШКА: Неочакван статус {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"ГРЕШКА ВЪВ ВРЪЗКАТА: {e}")
return False
if not validate_management_key():
sys.exit(1)
Периодична проверка на здравето (Healthcheck)
Периодичната проверка на здравето покрива онова, което валидирането при стартиране пропуска: дълготрайни услуги, стартирани преди седмици, чийто ключ може да изтече или да бъде отзован междувременно. Почасова проверка е достатъчна – крайната точка е лека и не консумира токени за извод (inference tokens).
#!/bin/bash
# healthcheck-xai.sh — изпълнява се всеки час чрез cron
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
"https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY")
if [ "$STATUS" != "200" ]; then
echo "ПРЕДУПРЕЖДЕНИЕ: Управленският ключ на xAI е невалиден (HTTP $STATUS)"
# Изпращане на предупреждение (PagerDuty, Slack, имейл)
fi
Одит на ключовете за извод (Inference keys)
Периодичният одит отговаря на три въпроса, които никое предупреждение няма да зададе вместо вас: кои ключове все още носят джокер (wildcard), кои нямат ограничения на скоростта и кои не са използвани от месеци. Първите две са рискове, третата е възможност за почистване – и всички три се обработват в един проход.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Одитира всички API ключове за екипа."""
response = requests.get(
f"{MANAGEMENT_API}/auth/teams/{TEAM_ID}/api-keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
keys = response.json().get("apiKeys", [])
print(f"=== Одит на API ключове — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Общ брой ключове: {len(keys)}")
for key in keys:
name = key.get("name", "Unnamed")
acls = key.get("acls", [])
expire = key.get("expireTime", "Never")
created = key.get("createdAt", "N/A")
# Предупреждения
warnings = []
# Ключ с достъп чрез джокер (wildcard)
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("ПЪЛЕН ДОСТЪП (джокери)")
# Ключ без срок на валидност
if expire == "Never" or not expire:
warnings.append("НЯМА СРОК НА ВАЛИДНОСТ")
# Ключ без ограничения на скоростта
if not key.get("qps") and not key.get("qpm"):
warnings.append("НЯМА ОГРАНИЧЕНИЯ НА СКОРОСТТА")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACLs: {len(acls)} | Изтича: {expire} | {status}")
audit_api_keys()
Контролен списък за сигурност на ключовете
Управленски ключове
Управленските ключове контролират всичко останало – компрометирането им предоставя достъп за създаване, модифициране и изтриване на всички ключове за извод. Затова те изискват най-строга обработка: изключително съхранение в трезор (vault), никога в чист текст в кода или версионираните конфигурации; достъп, ограничен само до администраторите на инфраструктурата, а не до разработчиците на приложения; и редовно валидиране чрез GET /auth/management-keys/validation, идеално автоматизирано като проверка на здравето – откриването на изтекъл управленски ключ в момент, когато спешно ви е нужен, е най-лошият оперативен сценарий.
Ключове за извод (API ключове)
За ключовете за извод водещият принцип е изолацията: всяко приложение получава свой собствен ключ, никога ключ, споделен между услуги – в противен случай ротацията на компрометиран ключ прекъсва всички услуги едновременно, а аналитиките вече не позволяват приписване на потреблението. Всеки ключ носи ограничителни ACL, калибрирани според реалната му употреба (без джокери в продукционна среда), ограничения на скоростта, оразмерени за очаквания трафик, и дата на изтичане, когато употребата е временна – доказателство за концепция (POC), предназначено да продължи две седмици, не се нуждае от вечен ключ. Редовният одит чрез горния скрипт затваря цикъла: той разкрива забравени, с прекалено широки права или изтичащи ключове, преди те да се превърнат в проблеми.
Принцип на разделяне на задълженията
Поддържайте ясно разделение между ключовете:
| Тип | Употреба | Кой има достъп |
|---|---|---|
| Управленски ключ | Администриране, фактуриране, аналитика | Администратори на инфраструктурата |
| Продукционен ключ | API извиквания в продукционна среда | Продукционно приложение |
| Staging ключ | Тестване преди продукционна среда | Екип за разработка |
| Dev ключ | Локална разработка | Индивидуален разработчик |
Всеки ключ има дефиниран обхват. Ако разработчик напусне екипа, се изтрива само неговият dev ключ – останалите остават непокътнати.
Ключови изводи
GET /auth/management-keys/validationпроверява валидността на вашия управленски ключ- Интегрирайте валидирането в стартирането на скриптовете и мониторинга си
- Одитирайте редовно всички ключове, за да откриете прекалено широк достъп
- Разделяйте ключовете по среда и отговорност
- Подавайте предупреждение незабавно при невалиден ключ (изтекъл или изтрит)