Vytvorenie a konfigurácia API kľúča
Na tejto strane
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]aleboapi-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