Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Juhtimisvõtme valideerimine

Õppetund 13 / 14 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Veendu oma võtmete terviklikkuses
  2. Valideerimise lõpp-punkt
  3. Integreerimine oma skriptidesse
  4. Järeldusvõtmete auditeerimine
  5. Võtmete turvalisuse kontrollnimekiri
  6. Kohustuste lahutamise põhimõte
  7. Peamised punktid

Veendu oma võtmete terviklikkuses

Juhtimisvõtme valideerimine on sinu API-taristu esimene kaitseliin. Enne mis tahes kriitilist toimingut – kasutuselevõtt, pööramine, arveldusmuudatused – veendu, et sinu võti on kehtiv ja selle õigused on korrektsed.

Valideerimise lõpp-punkt

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

Vastus kinnitab, et võti on aktiivne, ning tagastab meeskonna, õigused ja seotud kuupäevad. Ära jäta tähelepanuta aegumiskuupäeva: see on ainus teave, mis võimaldab sul katkestust ette näha, selle asemel et seda kannatada, sest aegunud võti ei hoiata sind – see tagastab lihtsalt koodi 401 esimesel järgneval päringul.

Veajuhtumid

  • 401 Unauthorized: Võti on kehtetu, aegunud või kustutatud
  • 403 Forbidden: Võti on kehtiv, kuid sellel puuduvad taotletud toiminguks vajalikud õigused

Integreerimine oma skriptidesse

Käivitamise kontroll

Valideerimine käivitamisel nihutab tõrke kohta, kus see maksab kõige vähem. Ilma selle kontrollita avaldub kehtetu võti esimesel kasulikul väljakutsel – see tähendab töötlemise keskel, mõnikord pärast seda, kui mitu sammu on juba täidetud. Sellega peatub skript kolme sekundiga koos sõnumiga, mis nimetab põhjuse.

import requests
import sys

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

def validate_management_key():
    """Kontrollib, kas juhtimisvõti on kehtiv."""
    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("Juhtimisvõti kehtiv")
            return True
        elif response.status_code == 401:
            print("VIGA: Juhtimisvõti kehtetu või aegunud")
            return False
        else:
            print(f"VIGA: Ootamatu olek {response.status_code}")
            return False
    except requests.exceptions.RequestException as e:
        print(f"ÜHENDUSE VIGA: {e}")
        return False

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

Perioodiline tervisekontroll

Perioodiline tervisekontroll katab selle, mida käivitamise kontroll vahele jätab: pikka aega töötavad teenused, mis on käivitatud nädalaid tagasi ja mille võti võib vahepeal aeguda või tühistada. Tunnine kontroll on piisav – lõpp-punkt on kerge ega tarbi järeldustokeneid.

#!/bin/bash
# healthcheck-xai.sh — käivita iga tund cron-i kaudu

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 "HOIATUS: xAI juhtimisvõti kehtetu (HTTP $STATUS)"
    # Saada hoiatus (PagerDuty, Slack, e-post)
fi

Järeldusvõtmete auditeerimine

Perioodiline auditeerimine vastab kolmele küsimusele, mida ükski hoiatus sinu eest ei küsi: millistel võtmetel on endiselt metamärk, millistel puuduvad kiirusepiirangud ja milliseid pole kuude kaupa kasutatud. Kaks esimest on riskid, kolmas võimalus koristada – ja kõiki kolme saab hallata ühe läbimisega.

import requests
from datetime import datetime

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

def audit_api_keys():
    """Auditeerib kõik meeskonna API-võtmed."""
    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-võtmete audit — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
    print(f"Võtmete koguarv: {len(keys)}")

    for key in keys:
        name = key.get("name", "Nimetu")
        acls = key.get("acls", [])
        expire = key.get("expireTime", "Mitte kunagi")
        created = key.get("createdAt", "N/A")

        # Hoiatused
        warnings = []

        # Võti metamärgiga juurdepääsuga
        if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
            warnings.append("TÄIELIK JUURDEPÄÄS (metamärgid)")

        # Võti ilma aegumiseta
        if expire == "Mitte kunagi" or not expire:
            warnings.append("AEGUMIST POLE")

        # Võti ilma kiirusepiiranguteta
        if not key.get("qps") and not key.get("qpm"):
            warnings.append("KIIRUSEPIIRANGUD PUUDUVAD")

        status = " | ".join(warnings) if warnings else "OK"
        print(f"  [{name}] ACL-id: {len(acls)} | Aegub: {expire} | {status}")

audit_api_keys()

Võtmete turvalisuse kontrollnimekiri

Juhtimisvõtmed

Juhtimisvõtmed kontrollivad kõike muud – nende kompromiteerimine annab juurdepääsu kõigi järeldusvõtmete loomiseks, muutmiseks ja kustutamiseks. Seetõttu nõuavad need kõige rangemat käsitlust: ainuõiguslik salvestamine võlvis, mitte kunagi lihttekstina koodis või versioonitud konfiguratsioonis; juurdepääs piiratud ainult taristu administraatoritele, mitte rakenduse arendajatele; ja regulaarne valideerimine kasutades GET /auth/management-keys/validation, ideaalis automatiseeritud tervisekontrollina – aegunud juhtimisvõtme avastamine hetkel, kui seda hädasti vaja läheb, on halvim operatiivne stsenaarium.

Järeldusvõtmed (API-võtmed)

Järeldusvõtmete puhul on juhtpõhimõtteks isolatsioon: iga rakendus saab oma võtme, mitte kunagi ei jagata võtit teenuste vahel – vastasel juhul rikub kompromiteeritud võtme pööramine korraga kõik teenused ja analüütika ei võimalda enam tarbimist omistada. Iga võti kannab piiravaid ACL-e, mis on kalibreeritud selle tegelikuks kasutuseks (tootmises metamärke ei ole), kiirusepiirangud, mis on mõõdetud oodatava liikluse jaoks, ja aegumiskuupäeva, kui kasutus on ajutine – kahe nädala kestvaks POC-iks pole vaja igavest võtit. Regulaarne auditeerimine ülaltoodud skriptiga sulgeb ahela: see paljastab unustatud, liigsete õigustega või aeguvad võtmed enne, kui need probleemideks muutuvad.

Kohustuste lahutamise põhimõte

Hoia võtmete vahel selget eraldatust:

TüüpKasutusKellel on juurdepääs
JuhtimisvõtiHaldus, arveldus, analüütikaTaristu administraatorid
TootevõtiAPI väljakutsed tootmisesTootmisrakendus
Testkeskkonna võtiEel-tootmise testimineArendusmeeskond
ArendusvõtiKohalik arendusIndividuaalne arendaja

Igal võtmel on määratletud ulatus. Kui arendaja lahkub meeskonnast, kustutatakse ainult tema arendusvõti – teised jäävad puutumata.

Peamised punktid

  • GET /auth/management-keys/validation kontrollib sinu juhtimisvõtme kehtivust
  • Integreeri valideerimine oma skripti käivitamisse ja jälgimisse
  • Auditeeri regulaarselt kõiki võtmeid, et tuvastada liiga laiaulatuslikku juurdepääsu
  • Eralda võtmed keskkonna ja vastutuse järgi
  • Teata koheselt kehtetust võtmest (aegunud või kustutatud)