Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Management-avaimen vahvistaminen

Oppitunti 13 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Varmista avaintesi eheys
  2. Validointipäätepiste
  3. Integrointi skripteihisi
  4. Inferenssiavainten auditointi
  5. Avainten tietoturvatarkistuslista
  6. Tehtävien eriyttämisen periaate
  7. Keskeiset asiat

Varmista avaintesi eheys

Management-avaimen validointi on API-infrastruktuurisi ensimmäinen puolustuslinja. Ennen kuin suoritat kriittisiä operaatioita – kuten käyttöönotto, kierto tai laskutuksen muutokset – varmista, että avaimesi on voimassa ja sen oikeudet ovat oikein määritetty.

Validointipäätepiste

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

Vastaus vahvistaa, että avain on aktiivinen, ja palauttaa tiimin, oikeudet sekä siihen liittyvät päivämäärät. Älä unohda vanhenemispäivää: tämä on ainoa tieto, jonka avulla voit ennakoida katkoksen sen sijaan, että joutuisit kärsimään siitä, sillä vanhentunut avain ei varoita sinua – se palauttaa yksinkertaisesti koodin 401 ensimmäisessä sitä seuraavassa pyynnössä.

Virhetilanteet

  • 401 Unauthorized: Avain on virheellinen, vanhentunut tai poistettu.
  • 403 Forbidden: Avain on voimassa, mutta sillä ei ole tarvittavia oikeuksia pyydettyyn operaatioon.

Integrointi skripteihisi

Käynnistyksen aikainen tarkistus

Validointi käynnistyksen yhteydessä siirtää virhetilanteet siihen vaiheeseen, jossa ne aiheuttavat vähiten haittaa. Ilman tätä tarkistusta virheellinen avain paljastuu vasta ensimmäisessä hyödyllisessä kutsussa – eli keskellä prosessointia, joskus useiden vaiheiden suorittamisen jälkeen. Tarkistuksen avulla skripti pysähtyy kolmessa sekunnissa viestin kera, joka nimeää syyn.

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)

Säännöllinen tilatarkistus (Healthcheck)

Säännöllinen tilatarkistus kattaa ne asiat, jotka käynnistyksen aikainen validointi jättää huomiotta: pitkään käynnissä olevat palvelut, jotka on aloitettu viikkoja sitten ja joiden avain voi vanhentua tai peruuntua matkan varrella. Tuntitarkistus riittää – päätepiste on kevyt eikä kuluta inferenssitokeneita.

#!/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

Inferenssiavainten auditointi

Säännöllinen auditointi vastaa kolmeen kysymykseen, joita hälytysjärjestelmä ei kysy puolestasi: millä avaimilla on edelleen jokerimerkki, millä ei ole nopeusrajoituksia ja mitä ei ole käytetty kuukausiin. Kaksi ensimmäistä ovat riskejä, kolmas mahdollisuus siivoukseen – ja kaikki kolme hoidetaan yhdellä ajokerralla.

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()

Avainten tietoturvatarkistuslista

Management-avaimet

Management-avaimet hallitsevat kaikkea muuta – niiden kompromissoituminen antaa pääsyn luoda, muokata ja poistaa kaikki inferenssiavaimet. Siksi niiden käsittely vaatii tiukimpia toimenpiteitä: yksinomainen säilytys holvissa, ei koskaan selväkielisenä koodissa tai versionoiduissa määrityksissä; pääsy rajoitettuna vain infrastruktuurin ylläpitäjille, ei sovelluskehittäjille; ja säännöllinen validointi komennolla GET /auth/management-keys/validation, ihanteellisesti automatisoituna tilatarkistuksena – vanhentunut management-avain, joka huomataan vasta silloin, kun sitä tarvitaan kiireellisesti, on pahin operatiivinen skenaario.

Inferenssiavaimet (API-avaimet)

Inferenssiavainten ohjaava periaate on eristäminen: jokainen sovellus saa oman avaimensa, ei koskaan palveluiden välillä jaettua avainta – muuten kompromissoituneen avaimen kierto rikkoo kaikki palvelut kerralla, eikä analytiikka enää mahdollista kulutuksen kohdistamista. Jokaiseen avaimeen liittyy sen todellista käyttöä vastaavat rajoittavat ACL:t (ei jokerimerkkejä tuotannossa), odotettua liikennettä varten mitoitetut nopeusrajoitukset ja vanhenemispäivä, jos käyttö on väliaikaista – kahden viikon POC ei tarvitse ikuista avainta. Säännöllinen auditointi yllä olevalla skriptillä sulkee silmukan: se paljastaa unohdetut, liian laajoja oikeuksia omaavat tai vanhenemassa olevat avaimet ennen kuin niistä tulee ongelmia.

Tehtävien eriyttämisen periaate

Pidä avainten välillä selkeä erottelu:

TyyppiKäyttöKenellä on pääsy
Management-avainHallinnointi, laskutus, analytiikkaInfrastruktuurin ylläpitäjät
TuotantoavainAPI-kutsut tuotannossaTuotantosovellus
TestausavainEsituotantotestausKehitystiimi
KehitysavainPaikallinen kehitysYksittäinen kehittäjä

Jokaisella avaimella on määritelty scope. Jos kehittäjä lähtee tiimistä, vain hänen kehitysavaimensa poistetaan – muut pysyvät ennallaan.

Keskeiset asiat

  • GET /auth/management-keys/validation tarkistaa management-avaimesi voimassaolon
  • Integroi validointi skriptiesi käynnistykseen ja valvontaan
  • Auditoida kaikki avaimet säännöllisesti liian laajojen oikeuksien havaitsemiseksi
  • Erota avaimet ympäristön ja vastuun mukaan
  • Hälytä välittömästi virheellisestä avaimesta (vanhentunut tai poistettu)