Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Vytvorenie a konfigurácia API kľúča

Lekcia 2 z 14 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Prečo vytvárať kľúče cez API
  2. Koncový bod pre vytvorenie
  3. Kompletný príklad s curl
  4. Odporúčané stratégie ACL
  5. Dostupné koncové body ACL
  6. Kľúčové poznatky

Prečo vytvárať kľúče cez API

Ručné vytvorenie kľúča trvá tridsať sekúnd – presne preto potrebuješ automatizáciu. Keďže je to rýchle, robíš to bez premýšľania: žiadna konvencia pomenovania, žiadne limity rýchlosti, len zástupný znak „aby sme boli rýchli“. O šesť mesiacov nikto nevie, na čo ktorý kľúč slúži.

Používanie API ťa núti každý kľúč pomenovať, definovať jeho rozsah a nastaviť limity, pretože ide o parametre skriptu. Konzistentnosť prestáva byť disciplínou, ktorú musíš udržiavať, a stáva sa vlastnosťou kódu. Môžeš automatizovať vytváranie kľúčov pre svoje prostredia (vývoj, testovanie, produkcia), aplikovať granularné zoznamy riadenia prístupu (ACL) a definovať limity rýchlosti – to všetko priamo v nasadzovacích skriptoch alebo nástrojoch infraštruktúry.

Koncový bod pre vytvorenie

Ak chceš vytvoriť API kľúč, pošli požiadavku POST na nasledujúci koncový bod:

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

Telo požiadavky

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

Podrobný popis parametrov

name (povinné): čitateľný identifikátor tvojho kľúča. Vyber opisný názov, ktorý naznačuje použitie (prod-backend, staging-chatbot, dev-john). Tento názov sa zobrazuje v konzole a v logoch využitia.

acls (povinné): zoznam oprávnení udelených tomuto kľúču. K dispozícii sú dva formáty:

  • api-key:endpoint:[endpoint] – obmedzuje prístupné koncové body (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] – obmedzuje použiteľné modely (grok-4.20-0309-reasoning, grok-4.3 atď.)

Znak * funguje ako zástupný znak: api-key:endpoint:* povoľuje všetky koncové body, api-key:model:* všetky modely. Toto si nechaj pre lokálny vývoj. V produkčnom prostredí znamená zástupný znak, že kompromitovaný kľúč poskytuje prístup ku všetkému, čo môže tvoj tím robiť – vrátane najdrahších modelov, ktoré tvoja aplikácia možno nikdy nepoužije.

qps (voliteľné): požiadavky za sekundu – maximálny počet požiadaviek za sekundu.

qpm (voliteľné): požiadavky za minútu – maximálny počet požiadaviek za minútu.

tpm (voliteľné): tokeny za minútu – maximálny počet tokenov spracovaných za minútu.

expireTime (voliteľné): dátum exspirácie vo formáte ISO 8601. Kľúč sa v tento dátum automaticky deaktivuje.

Kompletný príklad s 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"
  }'

Odozva obsahuje tajný kľúč, ktorý sa už nikdy viac nezobrazí. Toto pravidlo má praktický dôsledok, na ktorý musíš myslieť pred spustením skriptu, nie až po ňom: ak vytváraš kľúče v cykle, ukladanie musí prebehnúť v rovnakom kroku. Kľúč stratený medzi vytvorením a registráciou nie je možné obnoviť – musíš ho zmazať a začať odznova. Zapíš ho do trezora (Vault, AWS Secrets Manager), nie na štandardný výstup terminálu, kde skončí v tvojej histórii príkazov.

Odporúčané stratégie ACL

Vývojový kľúč (široký)

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

Ideálne pre lokálny vývoj: prístup je široký, pretože vopred nevieš, čo budeš skúšať, ale limity rýchlosti zostávajú nízke. Toto je správny kompromis – nekonečná slučka napísaná omylom v piatok večer bude stáť pár centov namiesto niekoľkých stoviek eur.

Produkčný kľúč (obmedzený)

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

V produkčnom prostredí sa pravidlo obracia: vychádzaj z toho, čo aplikácia skutočne robí, a povoľ iba to. Otázka, ktorú si musíš položiť pri písaní ACL, je vždy rovnaká – ak tento kľúč unikne zajtra, čo s ním môže tretia strana urobiť? Kľúč obmedzený na chat na jednom modeli a s limitom desať požiadaviek za sekundu dáva stručnú odpoveď.

Dočasný kľúč (s exspiráciou)

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

Automatická exspirácia rieši problém, ktorý nikto nerieši: kľúče, na ktoré ľudia zabudnú. POC, demonštrácia, dočasný dodávateľ – vo všetkých týchto prípadoch expireTime garantuje, že sa prístup sám vypne. Je to jediný spoľahlivý spôsob, ako udržať čistý inventár, pretože sa nespolieha na ničiu pamäť.

Dostupné koncové body ACL

Ak chceš vidieť koncové body, ktoré môžeš použiť v ACL, konzultuj:

GET /auth/teams/{teamId}/endpoints

Dostupné koncové body sú: chat, embed, image, models, sample, tokenize, documents. Tento zoznam sa môže časom meniť, preto ho pravidelne kontroluj.

Kľúčové poznatky

  • Vytvorenie kľúča prebieha cez POST /auth/teams/{teamId}/api-keys
  • ACL majú formát api-key:endpoint:[názov] alebo api-key:model:[názov]
  • Zástupný znak * udeľuje plný prístup ku všetkým koncovým bodom alebo modelom
  • Tajný kľúč sa zobrazí len raz pri vytvorení – okamžite ho ulož
  • Vždy definuj limity rýchlosti (qps, qpm, tpm) prispôsobené použitiu
  • Pre dočasné kľúče používaj expireTime