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

Seznam in spreminjanje vaših ključev

Lekcija 3 od 14 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Pregled vaših API ključev
  2. Izpis ključev
  3. Spreminjanje obstoječega ključa
  4. Preverjanje širjenja
  5. Pogosti scenariji
  6. Ključne ugotovitve

Pregled vaših API ključev

Sčasoma si vaša ekipa nabere API ključe za različna okolja, projekte in člane ekipe. Upravljalni API vam omogoča izpis vseh aktivnih ključev, filtriranje po dovoljenjih in spreminjanje njihovih nastavitev brez potrebe po ponovnem ustvarjanju.

Izpis ključev

Ta končna točka je izhodišče za vsak revizijski pregled dostopa in pogosto razkrije dejansko stanje: ključe, ustvarjene pred osmimi meseci za testiranje, ključ na ime nekdanjega člana ekipe ali dva produkcijska ključa, pri katerih nihče ne ve, kateri je v uporabi. Preden ustvarite kaj novega, najprej naredite seznam – morda ključ, ki ga potrebujete, že obstaja.

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

Parametri zahtevka

  • pageSize: število ključev na stran (privzeto so vrnjeni vsi ključi)
  • paginationToken: žeton za pridobitev naslednje strani, če število ključev preseže velikost strani
  • aclFilters: filtriranje ključev po določenih dovoljenjih

Filtriranje po ACL

Pridobite lahko le ključe z določeno ravnjo dostopa:

# Izpiši samo ključe z dostopom do klepeta
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

To filtriranje omogoča obvladljivo revizijo tudi pri več kot ducatu ključev. V praksi se pojavita dve vprašanji, na katera odgovori en sam zahtevek: kdo lahko kliče najdražji model in kateri ključi še vedno vsebujejo nadomestni znak. Drugo vprašanje je najbolj koristno – pozabljen nadomestni znak v produkciji je najpogostejša napaka v konfiguraciji in hkrati najbolj tiha.

Paginacija

Za ekipe z velikim številom ključev uporabite paginacijo:

# Prva stran z 10 ključi
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Naslednja stran s prejetim žetonom
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Spreminjanje obstoječega ključa

Spreminjanje namesto ponovnega ustvarjanja ni zgolj priročno: skrivni ključ ostane enak, zato ponovna namestitev ni potrebna. To vam omogoča prilagoditev omejitev ali omejitev dovoljenj brez prekinitve storitve – v primeru suma pa lahko v nekaj sekundah zmanjšate pravice ključa, medtem ko pripravljate njegovo zamenjavo.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v3",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning"
    ],
    "qps": 30,
    "qpm": 1000,
    "tpm": 3000000
  }'

Kaj lahko spremenite

  • name: preimenujte ključ, da odraža spremembo uporabe
  • acls: dodajte ali odstranite dovoljenja (končne točke, modeli)
  • qps / qpm / tpm: prilagodite omejitve hitrosti
  • expireTime: podaljšajte ali skrajšajte obdobje veljavnosti

Česa ne morete spremeniti

  • Identifikator ključa (api_key_id) ostane nespremenjen
  • Skrivni ključ se med spreminjanjem ne spremeni (za to uporabite zamenjavo)
  • Lastniške ekipe ni mogoče prenesti

Preverjanje širjenja

Tukaj je podrobnost, ki pojasnjuje polovico „napak”, prijavljenih po spremembi ključa: sprememba ni takojšnja na vseh strežnikih. Na novo ustvarjen ključ lahko za nekaj trenutkov vrne napako 401, razširjeni ACL morda še ni aktiven – in vi iščete napako v svoji kodi, čeprav bi morali le počakati. Končna točka za širjenje obstaja prav zato, da odpravi ta dvom:

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

Ta končna točka vrne stanje širjenja ključa. Pred uporabo ključa v produkciji, zlasti po spremembi ACL-jev, počakajte, da se širjenje zaključi.

Pogosti scenariji

Nadgradnja razvojnega ključa v produkcijskega

Prehod v produkcijo je najpogostejši scenarij spreminjanja, refleks ustvarjanja novega ključa ob tej priložnosti pa je drag: namestiti ga morate povsod, posodobiti trezorje, stari ključ pa ostane nedoločen čas. Zvišanje omejitev obstoječega ključa vse to prepreči.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-chatbot",
    "qps": 50,
    "qpm": 2000,
    "tpm": 5000000
  }'

Omejitev suma kompromitiranega ključa

V primeru suma je vrstni red operacij ključen. Najprej omejite – prazni ACL-ji, ničelne omejitve hitrosti – kar v enem zahtevku ustavi uhajanje, ne da bi kaj nepovratno pokvarili. Zamenjava sledi kasneje, offline, ko ugotovite, kje je bil ključ uporabljen. Obratni vrstni red pusti produkcijo nedelujočo in preiskavo, ki jo morate opraviti pod pritiskom.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acls": [],
    "qps": 0,
    "qpm": 0
  }'

Ključne ugotovitve

  • GET /auth/teams/{teamId}/api-keys izpiše vse ključe s paginacijo in filtriranjem po ACL
  • PUT /auth/api-keys/{apiKeyId} spremeni parametre brez spreminjanja skrivnega ključa
  • GET /auth/api-keys/{apiKeyId}/propagation preveri, ali so spremembe učinkovite
  • Uporabite filtriranje po ACL za redno revizijo dostopa vaše ekipe
  • Po vsaki spremembi pred uporabo ključa v produkciji preverite širjenje