Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Preverjanje veljavnosti upravljalnega ključa

Lekcija 13 od 14 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Preveri celovitost svojih ključev
  2. Končna točka za preverjanje
  3. Vključevanje v tvoje skripte
  4. Revizija ključev za sklepanje
  5. Kontrolni seznam za varnost ključev
  6. Načelo ločitve dolžnosti
  7. Ključne ugotovitve

Preveri celovitost svojih ključev

Preverjanje veljavnosti upravljalnega ključa je prva obrambna linija tvoje API infrastrukture. Pred vsako kritično operacijo – namestitvijo, zamenjavo ključa ali spremembami obračunavanja – preveri, ali je tvoj ključ veljaven in ali ima pravilna dovoljenja.

Končna točka za preverjanje

GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Odgovor potrdi, da je ključ aktiven, in vrne podatke o ekipi, dovoljenjih ter povezanih datumih. Ne spreglej datuma poteka: to je edina informacija, ki ti omogoča, da predvidiš izpad, namesto da bi ga utrpel, saj potekel ključ ne opozori – ob prvem naslednjem klicu preprosto vrne napako 401.

Primeri napak

  • 401 Unauthorized: Ključ je neveljaven, potekel ali izbrisan.
  • 403 Forbidden: Ključ je veljaven, vendar nima potrebnih dovoljenj za zahtevano operacijo.

Vključevanje v tvoje skripte

Preverjanje ob zagonu

Preverjanje ob zagonu prestavi morebitno napako na trenutek, ko so stroški najmanjši. Brez tega preverjanja se neveljaven ključ pokaže šele ob prvem uporabnem klicu – torej sredi obdelave, včasih potem, ko je bilo že opravljenih več korakov. S preverjanjem se skripta ustavi v treh sekundah z sporočilom, ki jasno navaja vzrok.

import requests
import sys

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."

def validate_management_key():
    """Checks that the management key is valid."""
    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("Management key valid")
            return True
        elif response.status_code == 401:
            print("ERROR: Management key invalid or expired")
            return False
        else:
            print(f"ERROR: Unexpected status {response.status_code}")
            return False
    except requests.exceptions.RequestException as e:
        print(f"CONNECTION ERROR: {e}")
        return False

if not validate_management_key():
    sys.exit(1)

Periodični zdravstveni pregled

Periodični zdravstveni pregled zajame tisto, kar preverjanje ob zagonu spusti: dolgotrajne storitve, zagnane pred tedni, katerih ključ lahko med delovanjem poteče ali pa je preklican. Urno preverjanje zadostuje – končna točka je lahka in ne porablja žetonov za sklepanje (inference tokens).

#!/bin/bash
# healthcheck-xai.sh — run every hour via 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 "ALERT: xAI management key invalid (HTTP $STATUS)"
    # Send an alert (PagerDuty, Slack, email)
fi

Revizija ključev za sklepanje

Periodična revizija odgovori na tri vprašanja, za katera te nobeno opozorilo ne bo vprašalo: kateri ključi še vedno nosijo nadomestni znak (wildcard), kateri nimajo omejitev hitrosti in kateri niso bili uporabljeni mesece. Prvi dve predstavljata tveganje, tretje pa priložnost za čiščenje – vse tri pa lahko obravnavaš v enem prehodu.

import requests
from datetime import datetime

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

def audit_api_keys():
    """Audits all API keys for the team."""
    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 Key Audit — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
    print(f"Total number of keys: {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")

        # Alerts
        warnings = []

        # Key with wildcard access
        if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
            warnings.append("TOTAL ACCESS (wildcards)")

        # Key without expiration
        if expire == "Never" or not expire:
            warnings.append("NO EXPIRATION")

        # Key without rate limits
        if not key.get("qps") and not key.get("qpm"):
            warnings.append("NO RATE LIMITS")

        status = " | ".join(warnings) if warnings else "OK"
        print(f"  [{name}] ACLs: {len(acls)} | Expire: {expire} | {status}")

audit_api_keys()

Kontrolni seznam za varnost ključev

Upravljalni ključi

Upravljalni ključi nadzorujejo vse ostalo – njihova ogroženost omogoča dostop do ustvarjanja, spreminjanja in brisanja vseh ključev za sklepanje. Zato zahtevajo najstrožje ravnanje: izključno shranjevanje v trezorju (vault), nikoli kot golo besedilo v kodi ali različno nadzorovani konfiguraciji; dostop omejen izključno na skrbnike infrastrukture, ne pa tudi na razvijalce aplikacij; in redno preverjanje veljavnosti prek GET /auth/management-keys/validation, idealno avtomatizirano kot zdravstveni pregled – odkritje poteklega upravljalnega ključa v trenutku, ko ga nujno potrebuješ, je najslabši operativni scenarij.

Ključi za sklepanje (API ključi)

Za ključe za sklepanje je vodilno načelo izolacija: vsaka aplikacija prejme svoj ključ, nikoli ključa, ki bi ga delile več storitev – v nasprotnem primeru zamenjava ogroženega ključa hkrati poruši vse storitve, analitika pa ne omogoča več pripisovanja porabe. Vsak ključ nosi omejevalne sezname nadzora dostopa (ACL), prilagojene njegovi dejanski uporabi (v proizvodnem okolju brez nadomestnih znakov), omejitve hitrosti, prilagojene pričakovanemu prometu, in datum poteka, če je uporaba začasna – dokazni koncept (POC), namenjen dvotedenski uporabi, ne potrebuje večne ključa. Redna revizija s pomočjo zgornje skripte zaključi krog: razkrije pozabljene, preveč pooblaščene ali ključe, ki jim bo kmalu potekla veljavnost, preden postanejo težava.

Načelo ločitve dolžnosti

Ohrani jasno ločitev med ključi:

VrstaUporabaKdo ima dostop
Upravljalni ključAdministracija, obračunavanje, analitikaSkrbniki infrastrukture
Proizvodni ključAPI klici v proizvodnem okoljuProizvodna aplikacija
Testni ključTestiranje pred proizvodnjoRazvojna ekipa
Razvojni ključLokalni razvojPosamezni razvijalec

Vsak ključ ima določen obseg. Če razvijalec zapusti ekipo, se izbriše le njegov razvojni ključ – ostali ostanejo nedotaknjeni.

Ključne ugotovitve

  • GET /auth/management-keys/validation preveri veljavnost tvojega upravljalnega ključa
  • Preverjanje vključi v zagon skripte in v nadzorovanje
  • Redno revidiraj vse ključe, da odkriješ preširok dostop
  • Loči ključe glede na okolje in odgovornost
  • Takoj opozori ob neveljavnem ključu (potekel ali izbrisan)