Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Vytvoření a konfigurace API klíče

Lekce 2 z 14 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Proč vytvářet klíče přes API
  2. Koncový bod pro vytvoření
  3. Kompletní příklad s curl
  4. Doporučené strategie ACL
  5. Dostupné koncové body ACL
  6. Klíčové poznatky

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] nebo api-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