Listaa ja muokkaa avaimiasi
Tällä sivulla
API-avainten inventaario
Ajan myötä tiimisi kerryttää API-avaimia eri ympäristöihin, projekteihin ja tiimin jäsenille. Hallinta-API:n avulla voit listata kaikki aktiiviset avaimet, suodattaa niitä käyttöoikeuksien perusteella ja muokata niiden asetuksia luomatta niitä uudelleen.
Avainten listaaminen
Tämä päätepiste on minkä tahansa käyttöoikeustarkastuksen lähtökohta, ja usein juuri täältä löytyy todellinen inventaario: kahdeksan kuukautta sitten testiä varten luotu avain, entisen tiimin jäsenen nimissä oleva avain tai kaksi tuotantoavainta, joista kukaan ei tiedä, kumpaa käytetään. Listaa avaimet ennen kuin luot uusia – tarvitsemasi avain saattaa olla jo olemassa.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Pyyntöparametrit
- pageSize: avainten määrä sivua kohden (oletuksena palautetaan kaikki avaimet)
- paginationToken: tunnus seuraavan sivun noutamiseen, jos avainten määrä ylittää sivukoon
- aclFilters: suodata avaimet tiettyjen käyttöoikeuksien perusteella
Suodatus ACL:n perusteella
Voit noutaa vain tietyllä käyttöoikeustasolla varustetut avaimet:
# Listaa vain chat-käyttöoikeuden omaavat avaimet
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Tämä suodatus tekee tarkastuksesta hallittavan, vaikka avaimia olisi yli kymmenen. Käytännössä nousee esiin kaksi kysymystä, joihin yksikin pyyntö vastaa: kuka voi kutsua kalleinta mallia, ja millä avaimilla on edelleen jokerimerkki. Jälkimmäinen on hyödyllisin – unohdettu jokerimerkki tuotannossa on yleisin konfiguraatiovirhe, ja samalla hiljaisin.
Sivutus
Tiimeille, joilla on paljon avaimia, käytä sivutusta:
# Ensimmäinen sivu, 10 avainta
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Seuraava sivu vastaanotetulla tunnuksella
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Olemassa olevan avaimen muokkaaminen
Uudelleenluonnin sijaan muokkaaminen ei ole pelkkää mukavuutta: salainen avain pysyy samana, joten uudelleenkäyttöönottoa ei tarvita. Tämä mahdollistaa rajoitusten säätämisen tai käyttöoikeuksien rajoittamisen ilman palvelukatkoa – ja epäilyttävissä tilanteissa voit vähentää avaimen oikeuksia sekunneissa samalla, kun valmistelet sen kierrätystä.
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
}'
Mitä voit muokata
- name: nimeä avain uudelleen käyttötarkoituksen muutoksen huomioon ottamiseksi
- acls: lisää tai poista käyttöoikeuksia (päätepisteet, mallit)
- qps / qpm / tpm: säädä nopeusrajoituksia
- expireTime: pidennä tai lyhennä voimassaoloaikaa
Mitä et voi muokata
- Avaimen tunniste (
api_key_id) pysyy muuttumattomana - Salainen avain ei muutu muokkauksen yhteydessä (käytä kierrätystä tähän)
- Omistavaa tiimiä ei voi siirtää
Tarkista levittyminen
Tässä on yksityiskohta, joka selittää puolet avaimen muokkauksen jälkeen ilmoitetuista “vioista”: muutos ei ole välitön kaikilla palvelimilla. Vastikään luotu avain saattaa palauttaa 401-virheen hetken aikaa, laajennettu ACL ei välttämättä ole vielä aktiivinen – ja etsit virhettä omasta koodistasi, vaikka olisi pitänyt vain odottaa. Levittymisen tarkistuspäätepiste on olemassa nimenomaan tämän epävarmuuden poistamiseksi:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Tämä päätepiste palauttaa avaimen levittymistilan. Odota levittymisen valmistumista ennen avaimen käyttöä tuotannossa, erityisesti ACL-muutosten jälkeen.
Yleisiä skenaarioita
Päivitä kehitysavain tuotantokäyttöön
Siirtyminen tuotantoon on yleisin muokkausskenaario, ja refleksi luoda uusi avain tätä varten on kallista: se on otettava käyttöön kaikkialla, holvit on päivitettävä, ja vanha avain jää lojumaan loputtomiin. Olemassa olevan avaimen rajoitusten nostaminen välttää kaiken tämän.
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
}'
Rajoita epäiltyä kompromissoitunutta avainta
Epäilyttävissä tilanteissa toimintajärjestyksellä on väliä. Rajoita ensin – tyhjät ACL:t, nollanopeusrajoitukset – tämä pysäyttää vuotojen aiheuttamat vahingot yhdellä pyynnöllä rikkomatta mitään peruuttamattomasti. Kierrätys tehdään myöhemmin offline-tilassa, kun olet selvittänyt, missä avainta on käytetty. Käänteinen järjestys jättää sinut tilanteeseen, jossa tuotanto on alhaalla ja tutkimus on tehtävä paineen alla.
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
}'
Keskeiset asiat
GET /auth/teams/{teamId}/api-keyslistaa kaikki avaimet sivutuksella ja ACL-suodatuksellaPUT /auth/api-keys/{apiKeyId}muokkaa parametreja muuttamatta salaista avaintaGET /auth/api-keys/{apiKeyId}/propagationvarmistaa, että muutokset ovat voimassa- Käytä ACL-suodatusta tiimisi käyttöoikeuksien säännölliseen tarkastamiseen
- Tarkista levittyminen minkä tahansa muokkauksen jälkeen ennen avaimen käyttöä tuotannossa