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

API võtme loomine ja seadistamine

Õppetund 2 / 14 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Miks luua võtmeid API kaudu
  2. Loomise lõpp-punkt
  3. Täielik näide curl-iga
  4. Soovitatavad ACL strateegiad
  5. Saadaval olevad ACL lõpp-punktid
  6. Peamised punktid

Miks luua võtmeid API kaudu

Võtme käsitsi loomine võtab kolmkümmend sekundit – just seetõttu vajadki automatiseerimist. Kuna protsess on kiire, teed seda mõtlemata: puudub nimekonventsioon, puuduvad kiirusepiirangud, lihtsalt üldine „liigu kiiresti“ lähenemine. Kuus kuud hiljem ei tea keegi, mida iga võti teeb.

API kasutamine sunnib sind igale võtmele nime andma, ulatust määratlema ja piiranguid seadma, kuna need on skripti parameetrid. Järjepidevus ei ole enam distsipliin, mida pead meeles pidama, vaid muutub koodi omaduseks. Saad automatiseerida võtmete loomist oma keskkondade jaoks (arendus, test, tootmine), rakendada granulaarseid ACL-e (juurdepääsukontrolli loendeid) ja määratleda kiirusepiiranguid – kõike seda oma kasutuselevõtu skriptides või infrastruktuuritööriistades.

Loomise lõpp-punkt

API võtme loomiseks saada POST päring järgmisse lõpp-punkti:

POST /auth/teams/{teamId}/api-keys

Päringu keha

{
  "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"
}

Üksikasjalikud parameetrid

name (kohustuslik): loetav identifikaator sinu võtmele. Vali kirjeldav nimi, mis näitab kasutusotstarvet (prod-backend, staging-chatbot, dev-john). See nimi kuvatakse konsoolis ja kasutuslogides.

acls (kohustuslik): sellele võtmele antud õiguste loend. Saadaval on kaks vormingut:

  • api-key:endpoint:[lõpp-punkt] — piirab ligipääsetavaid lõpp-punkte (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[mudel] — piirab kasutatavaid mudeleid (grok-4.20-0309-reasoning, grok-4.3 jne)

Märk * toimib üldmärkena: api-key:endpoint:* lubab kõiki lõpp-punkte, api-key:model:* kõiki mudeleid. Kasuta seda ainult kohalikuks arenduseks. Tootmiskeskkonnas tähendab üldmärk, et kompromiteeritud võti annab juurdepääsu kõigele, mida sinu meeskond teha saab – sealhulgas kõige kulukamatele mudelitele, mida sinu rakendus võib-olla kunagi ei kasuta.

qps (valikuline): päringuid sekundis – maksimaalne päringute arv sekundis.

qpm (valikuline): päringuid minutis – maksimaalne päringute arv minutis.

tpm (valikuline): tokenid minutis – maksimaalne töödeldud tokenite arv minutis.

expireTime (valikuline): aegumiskuupäev ISO 8601 vormingus. Võti keelatakse sellel kuupäeval automaatselt.

Täielik näide curl-iga

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

Vastus sisaldab salajast võtit, mida ei kuvata enam kunagi. Sellel reeglil on praktiline tagajärg, mille pead ette nägema enne skripti käivitamist, mitte pärast: kui lood võtmeid tsüklis, peab salvestamine toimuma samal ajal. Võti, mis läheb kaduma loomise ja registreerimise vahel, ei ole taastatav – pead selle kustutama ja otsast alustama. Kirjuta see võlvikusse (Vault, AWS Secrets Manager), mitte oma terminali standardväljundisse, kus see satub sinu ajalukku.

Soovitatavad ACL strateegiad

Arendusvõti (lai)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Ideaalne kohalikuks arenduseks: juurdepääs on lai, kuna sa ei tea ette, mida proovida soovid, kuid kiirusepiirangud jäävad madalaks. See on õige kompromiss – ekslikult reede õhtul kirjutatud lõpmatu tsükkel maksab mõned sendid, mitte sadu eurosid.

Tootmisvõti (piiratud)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

Tootmiskeskkonnas on reegel vastupidine: lähtu sellest, mida rakendus tegelikult teeb, ja luba ainult seda. Küsimus, mille pead ACL-i kirjutamisel endale alati esitama, on sama – kui see võti lekib homme, mida saab kolmas osapool sellega teha? Võti, mis on piiratud vestlusega ühel mudelil ja mille piirang on kümme päringut sekundis, annab lühikese vastuse.

Ajutine võti (aeguv)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

Automaatne aegumine lahendab probleemi, mida keegi ei haldaks: võtmed, mille unustatakse kustutada. POC, demonstratsioon, mööduv alltöövõtja – kõigil neil juhtudel garanteerib expireTime, et juurdepääs lülitub ise välja. See on ainus usaldusväärne viis puhta inventuuri hoidmiseks, kuna see ei sõltu kellegi mälust.

Saadaval olevad ACL lõpp-punktid

Et näha lõpp-punkte, mida saad ACL-ides kasutada, vaata:

GET /auth/teams/{teamId}/endpoints

Saadaval olevad lõpp-punktid on: chat, embed, image, models, sample, tokenize, documents. See loend võib ajas muutuda, seega kontrolli seda regulaarselt.

Peamised punktid

  • Võtme loomine toimub päringuga POST /auth/teams/{teamId}/api-keys
  • ACL-id järgivad vormingut api-key:endpoint:[nimi] või api-key:model:[nimi]
  • Üldmärk * annab täieliku juurdepääsu kõigile lõpp-punktidele või mudelitele
  • Salajast võtit kuvatakse ainult üks kord loomisel – salvesta see kohe
  • Määra alati kasutusele sobivad kiirusepiirangud (qps, qpm, tpm)
  • Kasuta ajutiste võtmete jaoks expireTime parameetrit