API võtme loomine ja seadistamine
Sellel lehel
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õiapi-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
expireTimeparameetrit