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

Loetle ja muuda oma võtmeid

Õppetund 3 / 14 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Sinu API-võtmete inventuur
  2. Võtmete loetlemine
  3. Olemasoleva võtme muutmine
  4. Kontrolli levikut
  5. Levinud stsenaariumid
  6. Peamised punktid

Sinu API-võtmete inventuur

Aja jooksul koguneb sinu meeskonnale API-võtmeid erinevate keskkondade, projektide ja liikmete jaoks. Haldus-API võimaldab sul loetleda kõik aktiivsed võtmed, filtreerida neid õiguste põhjal ja muuta nende seadeid ilma võtmeid uuesti loomata.

Võtmete loetlemine

See lõpp-punkt on iga juurdepääsuauditi lähtepunkt ja sageli just siit avastad tegeliku seisuse: kaheksa kuud tagasi testiks loodud võti, endise meeskonnaliikme nimele registreeritud võti või kaks tootmisvõtit, millest keegi ei tea, kumb kasutusel on. Enne uue loomist tee loendus – võib-olla on sul vajalik võti juba olemas.

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

Päringu parameetrid

  • pageSize: võtmete arv lehe kohta (vaikimisi tagastatakse kõik võtmed)
  • paginationToken: token järgmise lehe toomiseks, kui võtmete arv ületab lehe suuruse
  • aclFilters: filtreeri võtmeid kindlate õiguste põhjal

Filtreerimine ACL-i järgi

Saad tuua ainult teatud juurdepääsutasemega võtmed:

# Loetle ainult vestluse õigusega võtmed
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Just see filtreerimine muudab auditi hallatavaks ka siis, kui võtmeid on rohkem kui tosin. Praktikas kerkib kaks küsimust, millele vastab üksainus päring: kes saab kutsuda kõige kallimat mudelit ja millistel võtmetel on endiselt üldine õigus (wildcard). Teine neist on kõige kasulikum – unustatud üldine õigus tootmiskeskkonnas on kõige levinum ja vaikseim konfiguratsiooniviga.

Paginatsioon

Meeskondadele, kellel on palju võtmeid, kasuta paginatsiooni:

# Esimene leht 10 võtmega
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Järgmine leht saadud tokeniga
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Olemasoleva võtme muutmine

Uuesti loomise asemel muutmine ei ole pelgalt mugavus: salajane võti jääb samaks, seega ei ole vaja uut kasutuselevõttu. See võimaldab sul kohandada piiranguid või kitsendada õigusi ilma teenuse katkestuseta – ja kahtluse korral vähendada võtme õigusi sekunditega, samal ajal kui valmistad ette selle vahetust.

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
  }'

Mida saad muuta

  • name: nimeta võti ümber, et kajastada kasutuse muutust
  • acls: lisa või eemalda õigusi (lõpp-punktid, mudelid)
  • qps / qpm / tpm: kohanda kiiruse piiranguid
  • expireTime: pikenda või lühenda kehtivusaega

Mida ei saa muuta

  • Võtme identifikaator (api_key_id) jääb muutumatuks
  • Salajane võti muutumise käigus ei muutu (selleks kasuta vahetust)
  • Omavat meeskonda ei saa üle kanda

Kontrolli levikut

Siin on detail, mis selgitab poolt pärast võtme muutmist teatatud „vigadest“: muutus ei jõustu kõigis serverites koheselt. Värskelt loodud võti võib mõne hetke jooksul tagastada veakoodi 401, laiendatud ACL pruugi veel aktiivne olla – ja sa otsid viga oma koodist, kuigi oleks pidanud lihtsalt ootama. Leviku lõpp-punkt on loodud just selle kahtluse kõrvaldamiseks:

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

See lõpp-punkt tagastab võtme leviku oleku. Oota leviku lõpuleviimist enne võtme kasutamist tootmiskeskkonnas, eriti pärast ACL-ide muutmist.

Levinud stsenaariumid

Arendusvõtme uuendamine tootmisvõtmeks

Tootmisse üleminek on kõige levinum muutmise stsenaarium ja refleks sellisel puhul uus võti luua on kulukas: pead selle kõikjale kasutusele võtma, uuendama turvahoidlaid ja vana võti jääb määramata ajaks alles. Olemasoleva võtme piirangute tõstmine väldib kõike seda.

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
  }'

Kahtluse all oleva kompromiteeritud võtme piiramine

Kahtluse korral on toimingute järjekord otsustava tähtsusega. Esmalt piira – tühjad ACL-id, nullitud kiiruse piirangud – peatab verejooksu ühe päringuga, murdmata midagi pöördumatult. Vahetus tuleb hiljem, offline-režiimis, kui oled tuvastanud, kus võtit kasutati. Vastupidine järjestus jätab sind seisuga, kus tootmine on maas, ja sunnib läbi viima uurimist surve all.

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
  }'

Peamised punktid

  • GET /auth/teams/{teamId}/api-keys loetleb kõik võtmed koos paginatsiooni ja ACL-filtreerimisega
  • PUT /auth/api-keys/{apiKeyId} muudab parameetreid ilma salajast võtit muutmata
  • GET /auth/api-keys/{apiKeyId}/propagation kontrollib, kas muudatused on jõustunud
  • Kasuta ACL-filtreerimist oma meeskonna juurdepääsu regulaarseks auditeerimiseks
  • Pärast igat muudatust kontrolli levikut enne võtme kasutamist tootmiskeskkonnas