Vytvoření a konfigurace API klíče
Na této stránce
Proč vytvářet klíče přes API
Ruční vytvoření klíče zabere třicet sekund – a přesně proto potřebuješ automatizaci. Protože je to rychlé, děláš to bez přemýšlení: žádná konvence pojmenování, žádné limity rychlosti, jen zástupný znak „aby to šlo rychle“. O šest měsíců později nikdo neví, k čemu který klíč slouží.
Použití API tě donutí každý klíč pojmenovat, definovat jeho rozsah a nastavit limity, protože se jedná o parametry skriptu. Konzistence přestává být disciplínou, kterou musíš udržovat, a stává se vlastností kódu. Můžeš automatizovat vytváření klíčů pro svá prostředí (vývoj, staging, produkce), aplikovat granularní seznamy řízení přístupu (ACL) a definovat limity rychlosti – vše přímo ve svých nasazovacích skriptech nebo infrastrukturních nástrojích.
Koncový bod pro vytvoření
Chceš-li vytvořit API klíč, odešli požadavek POST na následující koncový bod:
POST /auth/teams/{teamId}/api-keys
Tělo požadavku
{
"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 parametrů
name (povinné): čitelný identifikátor tvého klíče. Zvol popisný název, který indikuje využití (prod-backend, staging-chatbot, dev-john). Tento název se zobrazuje v konzoli a v logách využití.
acls (povinné): seznam oprávnění udělených tomuto klíči. K dispozici jsou dva formáty:
api-key:endpoint:[endpoint]– omezuje přístupné koncové body (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]– omezuje použitelné modely (grok-4.20-0309-reasoning, grok-4.3 atd.)
Znak * funguje jako zástupný znak: api-key:endpoint:* autorizuje všechny koncové body, api-key:model:* všechny modely. Toto si nech pro lokální vývoj. V produkci znamená zástupný znak, že kompromitovaný klíč poskytuje přístup ke všemu, co může tvůj tým dělat – včetně nejdražších modelů, které tvoje aplikace možná nikdy nepoužije.
qps (volitelné): dotazy za sekundu – maximální počet požadavků za sekundu.
qpm (volitelné): dotazy za minutu – maximální počet požadavků za minutu.
tpm (volitelné): tokeny za minutu – maximální počet tokenů zpracovaných za minutu.
expireTime (volitelné): datum vypršení platnosti ve formátu ISO 8601. Klíč se k tomuto datu automaticky deaktivuje.
Kompletní pří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"
}'
Odpověď obsahuje tajný klíč, který již nikdy nebude znovu zobrazen. Toto pravidlo má praktický důsledek, který musíš anticipovat před spuštěním skriptu, ne až po něm: pokud vytváříš klíče v cyklu, musí k uložení dojít ve stejném okamžiku. Klíč ztracený mezi vytvořením a registrací nelze obnovit – musíš jej smazat a začít od začátku. Zapiš jej do trezoru (Vault, AWS Secrets Manager), nikoliv na standardní výstup terminálu, kde skončí v historii příkazů.
Doporučené strategie ACL
Vývojový klíč (široký)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Ideální pro lokální vývoj: přístup je široký, protože předem nevíš, co budeš zkoušet, ale limity rychlosti zůstávají nízké. To je správný kompromis – nekonečná smyčka napsaná omylem v pátek večer bude stát pár centů místo několika stovek eur.
Produkční klíč (omezený)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
V produkci se pravidlo obrací: vyjdi z toho, co aplikace skutečně dělá, a autorizuj pouze to. Otázka, kterou si musíš položit při psaní ACL, je vždy stejná – pokud tento klíč zítra unikne, co s ním může třetí strana dělat? Klíč omezený na chat na jediném modelu a s limitem deseti požadavků za sekundu dává stručnou odpověď.
Dočasný klíč (s expirací)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
Automatická expirace řeší problém, který nikdo neřeší: klíče, na které lidé zapomenou. POC, demonstrace, dočasný dodavatel – ve všech těchto případech expireTime zaručuje, že se přístup sám vypne. Je to jediný spolehlivý způsob, jak udržovat čistý inventář, protože se nespoléhá na ničí paměť.
Dostupné koncové body ACL
Chceš-li vidět koncové body, které můžeš použít v ACL, konzultuj:
GET /auth/teams/{teamId}/endpoints
Dostupné koncové body jsou: chat, embed, image, models, sample, tokenize, documents. Tento seznam se může časem měnit, proto jej pravidelně kontroluj.
Klíčové poznatky
- Vytváření klíčů probíhá přes
POST /auth/teams/{teamId}/api-keys - ACL mají formát
api-key:endpoint:[název]neboapi-key:model:[název] - Zástupný znak
*uděluje plný přístup ke všem koncovým bodům nebo modelům - Tajný klíč je zobrazen pouze jednou při vytvoření – okamžitě jej ulož
- Vždy definuj limity rychlosti (
qps,qpm,tpm) přizpůsobené využití - Pro dočasné klíče používej
expireTime