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

Валидиране на управленския ключ

Урок 13 от 14 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. Проверка на целостта на вашите ключове
  2. Крайна точка за валидиране
  3. Интегриране във вашите скриптове
  4. Одит на ключовете за извод (Inference keys)
  5. Контролен списък за сигурност на ключовете
  6. Принцип на разделяне на задълженията
  7. Ключови изводи

Проверка на целостта на вашите ключове

Валидирането на управленския ключ е първата линия на защита на вашата 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 проверява валидността на вашия управленски ключ
  • Интегрирайте валидирането в стартирането на скриптовете и мониторинга си
  • Одитирайте редовно всички ключове, за да откриете прекалено широк достъп
  • Разделяйте ключовете по среда и отговорност
  • Подавайте предупреждение незабавно при невалиден ключ (изтекъл или изтрит)