Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Ustvari in konfiguriraj ključ API

Lekcija 2 od 14 Posodobljeno 29. julij 2026 Razvijalec
Na tej strani
  1. Zakaj ustvarjati ključe prek API-ja
  2. Končna točka za ustvarjanje
  3. Celoten primer z ukazom curl
  4. Priporočene strategije ACL
  5. Razpoložljive končne točke ACL
  6. Ključne ugotovitve

Zakaj ustvarjati ključe prek API-ja

Ročno ustvarjanje ključa traja trideset sekund – kar je ravno razlog, zakaj potrebuješ avtomatizacijo. Ker je postopek hiter, ga opraviš brez razmisleka: brez poimenovalnih konvencij, brez omejitev hitrosti, le nadomestni znak za „hitro delovanje”. Šest mesecev kasneje nihče ne ve, kateri ključ kaj počne.

Uporaba API-ja te prisili, da vsak ključ poimenuješ, določiš njegov obseg in omejiš, saj so to parametri skripte. Doslednost preneha biti disciplina, ki jo moraš vzdrževati, in postane lastnost kode. Ustvarjanje ključev za svoja okolja (razvojno, testno, produkcijsko) lahko avtomatiziraš, uporabiš granularne sezname nadzora dostopa (ACL) in določiš omejitve hitrosti – vse to znotraj svojih skript za uvajanje ali orodij za infrastrukturo.

Končna točka za ustvarjanje

Če želiš ustvariti ključ API, pošlji zahtevo POST na naslednjo končno točko:

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

Telo zahteve

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

Podrobni parametri

name (obvezno): berljiv identifikator za tvoj ključ. Izberi opisno ime, ki kaže na uporabo (prod-backend, staging-chatbot, dev-john). To ime se prikaže v konzoli in v dnevnikih uporabe.

acls (obvezno): seznam dovoljenj, dodeljenih temu ključu. Na voljo sta dve obliki:

  • api-key:endpoint:[endpoint] – omeji dostopne končne točke (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] – omeji uporabne modele (grok-4.20-0309-reasoning, grok-4.3 itd.)

Znak * deluje kot nadomestni znak: api-key:endpoint:* avtorizira vse končne točke, api-key:model:* vse modele. To uporabi zgolj za lokalni razvoj. V produkcijskem okolju nadomestni znak pomeni, da kompromitiran ključ omogoča dostop do vsega, kar lahko stori tvoja ekipa – vključno z najdražjimi modeli, ki jih tvoja aplikacija morda nikoli ne uporablja.

qps (izbirno): poizvedbe na sekundo – največje število zahtev na sekundo.

qpm (izbirno): poizvedbe na minuto – največje število zahtev na minuto.

tpm (izbirno): žetoni na minuto – največje število obdelanih žetonov na minuto.

expireTime (izbirno): datum poteka v formatu ISO 8601. Ključ se na ta datum samodejno onemogoči.

Celoten primer z ukazom curl

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

Odgovor vsebuje tajni ključ, ki ne bo nikoli več prikazan. To pravilo ima praktično posledico, ki jo moraš predvideti pred zagonom skripte, ne po njem: če ustvarjaš ključe v zanki, mora shranjevanje potekati v istem koraku. Ključ, izgubljen med ustvarjanjem in registracijo, ni mogoče obnoviti – izbrisati ga moraš in začeti znova. Zapiši ga v trezor (Vault, AWS Secrets Manager), ne pa v standardni izhod terminala, kjer bo končal v tvoji zgodovini ukazov.

Priporočene strategije ACL

Razvojni ključ (širok)

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

Idealno za lokalni razvoj: dostop je širok, ker vnaprej ne veš, kaj boš preizkušal, vendar so omejitve hitrosti nizke. To je pravi kompromis – neskončna zanka, ki jo pomotoma napišeš petek zvečer, bo stala nekaj centov namesto nekaj sto evrov.

Produkcijski ključ (omejen)

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

V produkcijskem okolju se pravilo obrne: začni s tem, kaj aplikacija dejansko počne, in avtoriziraj le to. Vprašanje, ki si ga moraš zastaviti pri pisanju ACL, je vedno enako – če ta ključ uhaja jutri, kaj lahko z njim stori tretja oseba? Ključ, omejen na klepet na enem samem modelu in omejen na deset zahtev na sekundo, da kratek odgovor.

Začasni ključ (s potekom)

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

Samodejni potek reši težavo, ki je nihče ne obravnava: ključi, ki jih ljudje pozabijo izbrisati. Dokaz koncepta (POC), demonstracija, zunanj sodelavec – v vseh teh primerih expireTime zagotavlja, da se dostop sam izklopi. To je edini zanesljiv način za vzdrževanje čistega inventarja, saj se ne zanaša na nikogaršnji spomin.

Razpoložljive končne točke ACL

Če želiš videti končne točke, ki jih lahko uporabiš v ACL-jih, si oglej:

GET /auth/teams/{teamId}/endpoints

Razpoložljive končne točke so: chat, embed, image, models, sample, tokenize, documents. Ta seznam se lahko s časom spremeni, zato ga redno preverjaj.

Ključne ugotovitve

  • Ustvarjanje ključev poteka prek POST /auth/teams/{teamId}/api-keys
  • ACL-ji sledijo formatu api-key:endpoint:[ime] ali api-key:model:[ime]
  • Nadomestni znak * podeli poln dostop do vseh končnih točk ali modelov
  • Tajni ključ je prikazan le enkrat ob ustvarjanju – takoj ga shrani
  • Vedno določi omejitve hitrosti (qps, qpm, tpm), prilagojene uporabi
  • Za začasne ključe uporabi expireTime