Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Stvaranje i konfiguracija API ključa

Lekcija 2 od 14 Ažurirano 29. srpnja 2026. Programer
Na ovoj stranici
  1. Zašto stvarati ključeve putem API-ja
  2. Krajnja točka za stvaranje
  3. Potpuni primjer s curlom
  4. Preporučene strategije ACL-a
  5. Dostupne ACL krajnje točke
  6. Ključne točke

Zašto stvarati ključeve putem API-ja

Ručno stvaranje ključa traje trideset sekundi—upravo zato ti treba automatizacija. Budući da je brzo, to radiš bez razmišljanja: bez konvencije imenovanja, bez ograničenja stope, samo divlji znak „da se ubrza“. Šest mjeseci kasnije, nitko ne zna što koji ključ radi.

Korištenje API-ja prisiljava te da imenuješ, definiraš opseg i ograničiš svaki ključ jer su to parametri skripte. Dosljednost prestaje biti disciplina koju moraš održavati i postaje svojstvo koda. Možeš automatizirati stvaranje ključeva za svoja okruženja (dev, staging, production), primijeniti granularne ACL-ove i definirati ograničenja stope—sve unutar svojih skripti za implementaciju ili alata za infrastrukturu.

Krajnja točka za stvaranje

Za stvaranje API ključa pošalji POST zahtjev na sljedeću krajnju točku:

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

Tijelo zahtjeva

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

Detaljni parametri

name (obavezno): čitljiv identifikator za tvoj ključ. Odaberi opisno ime koje ukazuje na namjenu (prod-backend, staging-chatbot, dev-john). Ovo se ime pojavljuje u konzoli i u zapisnicima korištenja.

acls (obavezno): popis dopuštenja dodijeljenih ovom ključu. Dostupna su dva formata:

  • api-key:endpoint:[endpoint] — ograničava dostupne krajnje točke (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] — ograničava modele koje se mogu koristiti (grok-4.20-0309-reasoning, grok-4.3, itd.)

Znak * djeluje kao divlji znak: api-key:endpoint:* odobrava sve krajnje točke, api-key:model:* sve modele. Ovo rezerviraj za lokalni razvoj. U produkciji, divlji znak znači da kompromitirani ključ daje pristup svemu što tvoj tim može učiniti—uključujući najskuplje modele koje tvoja aplikacija možda nikada neće koristiti.

qps (opcionalno): upiti u sekundi — maksimalan broj zahtjeva u sekundi.

qpm (opcionalno): upiti u minuti — maksimalan broj zahtjeva u minuti.

tpm (opcionalno): tokeni u minuti — maksimalan broj tokena obrađenih u minuti.

expireTime (opcionalno): datum isteka u ISO 8601 formatu. Ključ će se automatski onemogućiti na taj datum.

Potpuni primjer s curlom

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 sadrži tajni ključ koji se nikada više neće prikazati. Ovo pravilo ima praktičnu posljedicu koju moraš predvidjeti prije pokretanja skripte, a ne nakon: ako stvaraš ključeve u petlji, pohrana se mora dogoditi u istom trenutku. Ključ izgubljen između stvaranja i registracije nije moguće oporaviti—moraš ga izbrisati i početi ispočetka. Zapiši ga u trezor (Vault, AWS Secrets Manager), a ne u standardni izlaz svog terminala gdje će završiti u tvojoj povijesti.

Preporučene strategije ACL-a

Razvojni ključ (širok)

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

Idealno za lokalni razvoj: pristup je širok jer unaprijed ne znaš što ćeš isprobavati, ali ograničenja stope ostaju niska. To je pravi kompromis—beskonačna petlja napisana greškom petkom navečer koštat će nekoliko centi umjesto nekoliko stotina eura.

Produkcijski ključ (ograničen)

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

U produkciji pravilo se okreće: kreni od onoga što aplikacija zapravo radi i odobri samo to. Pitanje koje si moraš postaviti pri pisanju ACL-a uvijek je isto—što treća strana može učiniti s ovim ključem ako procuri sutra? Ključ ograničen na chat na jednom modelu i capped na deset zahtjeva u sekundi daje kratak odgovor.

Privremeni ključ (s istekom)

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

Automatski istek rješava problem kojim se nitko ne bavi: ključevi koje ljudi zaborave izbrisati. POC, demonstracija, prolazni suradnik—u svim tim slučajevima expireTime jamči da se pristup sam gasi. Ovo je jedini pouzdan način održavanja čistog inventara jer se ne oslanja na ničije pamćenje.

Dostupne ACL krajnje točke

Da bi vidio/la krajnje točke koje možeš koristiti u ACL-ovima, konzultiraj:

GET /auth/teams/{teamId}/endpoints

Dostupne krajnje točke su: chat, embed, image, models, sample, tokenize, documents. Ovaj se popis može mijenjati tijekom vremena, pa ga redovito provjeravaj.

Ključne točke

  • Stvaranje ključa događa se putem POST /auth/teams/{teamId}/api-keys
  • ACL-ovi slijede format api-key:endpoint:[ime] ili api-key:model:[ime]
  • Divlji znak * dodjeljuje puni pristup svim krajnjim točkama ili modelima
  • Tajni ključ prikazuje se samo jednom pri stvaranju—odmah ga spremi
  • Uvijek definiraj ograničenja stope (qps, qpm, tpm) prilagođena korištenju
  • Koristi expireTime za privremene ključeve