API-avaimen luominen ja konfigurointi
Tällä sivulla
Miksi avaimia kannattaa luoda API:n kautta
Avaimen luominen manuaalisesti vie kolmekymmentä sekuntia – ja juuri siksi tarvitset automaatiota. Koska se on nopeaa, teet sen miettimättä: ei nimeämiskäytäntöjä, ei nopeusrajoituksia, vain villikortti “nopeutta varten”. Kuuden kuukauden kuluttua kukaan ei tiedä, mitä kukin avain tekee.
API:n käyttö pakottaa sinut nimeämään, rajaamaan ja asettamaan katon jokaiselle avaimelle, koska nämä ovat skriptin parametreja. Johdonmukaisuus lakkaa olemasta ylläpidettävä kurinpidon muoto ja muuttuu koodin ominaisuudeksi. Voit automatisoida avainten luonnin ympäristöillesi (dev, staging, production), soveltaa hienojakoisia käyttöoikeuksia (ACL) ja määritellä nopeusrajoitukset – kaikki tämä suoraan käyttöönottoskripteissäsi tai infrastruktuurityökaluissasi.
Luontipäätepiste
API-avaimen luomiseksi lähetä POST-pyyntö seuraavaan päätepisteeseen:
POST /auth/teams/{teamId}/api-keys
Pyyntörunko
{
"name": "ma-cle-production",
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 10,
"qpm": 100,
"tpm": 1000000,
"expireTime": "2026-12-31T23:59:59Z"
}
Parametrien yksityiskohdat
name (pakollinen): avaimellesi luettava tunniste. Valitse kuvaava nimi, joka kertoo käyttötarkoituksesta (prod-backend, staging-chatbot, dev-john). Tämä nimi näkyy konsolissa ja käyttölokeissa.
acls (pakollinen): luettelo tälle avaimelle myönnetyistä käyttöoikeuksista. Käytettävissä on kaksi muotoa:
api-key:endpoint:[endpoint]– rajoittaa käytettäviä päätepisteitä (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]– rajoittaa käytettäviä malleja (grok-4.20-0309-reasoning, grok-4.3 jne.)
Merkki * toimii villikorttina: api-key:endpoint:* valtuuttaa kaikki päätepisteet, api-key:model:* kaikki mallit. Varaa tämä paikalliseen kehitykseen. Tuotannossa villikortti tarkoittaa, että kompromissoitunut avain antaa pääsyn kaikkeen, mitä tiimisi voi tehdä – mukaan lukien kalleimpiin malleihin, joita sovelluksesi ei ehkä koskaan käytä.
qps (valinnainen): kyselyjä sekunnissa – suurin sallittu pyyntöjen määrä sekunnissa.
qpm (valinnainen): kyselyjä minuutissa – suurin sallittu pyyntöjen määrä minuutissa.
tpm (valinnainen): tokenia minuutissa – suurin sallittu käsiteltyjen tokenien määrä minuutissa.
expireTime (valinnainen): vanhenemispäivä ISO 8601 -muodossa. Avain poistuu käytöstä automaattisesti tähän päivämäärään mennessä.
Täydellinen esimerkki curlilla
curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v2",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning",
"api-key:model:grok-4.3"
],
"qps": 20,
"qpm": 500,
"tpm": 2000000,
"expireTime": "2027-06-30T23:59:59Z"
}'
Vastaus sisältää salaisen avaimen, jota ei koskaan näytetä uudelleen. Tällä säännöllä on käytännön seuraus, joka sinun on ennakoitava ennen skriptin ajamista, ei sen jälkeen: jos luot avaimia silmukassa, tallennuksen on tapahduttava samalla kertaa. Avain, joka katoaa luonnin ja rekisteröinnin välissä, ei ole palautettavissa – sinun on poistettava se ja aloitettava alusta. Kirjoita se holviin (Vault, AWS Secrets Manager) eikä päätteesi vakio-outputsille, josta se päätyy komentohistoriaasi.
Suositellut ACL-strategiat
Kehitysavain (laaja)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Ihanteellinen paikalliseen kehitykseen: pääsy on laaja, koska et tiedä etukäteen, mitä aiot kokeilla, mutta nopeusrajoitukset pysyvät alhaisina. Tämä on oikea kompromissi – vahingossa perjantai-iltana kirjoitettu ääretön silmukka maksaa muutaman sentin eikä satoja euroja.
Tuotantoavain (rajoitettu)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
Tuotannossa sääntö kääntyy päinvastaiseksi: lähde liikkeelle siitä, mitä sovellus todella tekee, ja valtuuta vain se. Kysymys, joka sinun tulee aina esittää ACL:ää kirjoittaessasi, on sama – jos tämä avain vuotaa huomenna, mitä kolmas osapuoli voi sillä tehdä? Avain, joka on rajoitettu chattiin yhdellä mallilla ja rajattu kymmeneen pyyntöön sekunnissa, antaa lyhyen vastauksen.
Väliaikainen avain (vanheneva)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
Automaattinen vanheneminen ratkaisee ongelman, jota kukaan ei hoida: avaimet, jotka ihmiset unohtavat poistaa. POC, demonstraatio, ohimenevä urakoitsija – kaikissa näissä tapauksissa expireTime takaa, että pääsy katkeaa itsestään. Tämä on ainoa luotettava tapa ylläpitää siistiä inventaariota, koska se ei luota kenenkään muistiin.
Käytettävissä olevat ACL-päätepisteet
Nähdäksesi ACL:ssä käytettävissä olevat päätepisteet, katso:
GET /auth/teams/{teamId}/endpoints
Käytettävissä olevat päätepisteet ovat: chat, embed, image, models, sample, tokenize, documents. Tämä luettelo voi kehittyä ajan myötä, joten tarkista se säännöllisesti.
Keskeiset asiat
- Avaimen luonti tapahtuu osoitteeseen
POST /auth/teams/{teamId}/api-keys - ACL:t noudattavat muotoa
api-key:endpoint:[nimi]taiapi-key:model:[nimi] - Villikortti
*myöntää täyden pääsyn kaikkiin päätepisteisiin tai malleihin - Salainen avain näytetään vain kerran luonnin yhteydessä – tallenna se välittömästi
- Määritä aina käyttöön sopivat nopeusrajoitukset (
qps,qpm,tpm) - Käytä
expireTime-parametria väliaikaisille avaimille