Autentizace
API používá osobní API klíče (Personal API Keys) pro autentizaci. Každý klíč je vázaný na uživatele a dědí jeho roli a oprávnění — nikdy je nerozšiřuje. Stejný klíč funguje i pro MCP server.
API a MCP jsou součástí tarifu Starter a vyšších (zkušební doba má funkce tarifu Business). Organizace na tarifu Free — typicky po skončení zkušební doby — dostane na každý požadavek chybu 403 „API a MCP jsou od tarifu Starter…“ a nový klíč si nevytvoří. Klíče ani připojené aplikace se nemažou: po přechodu na vyšší tarif (vlastník nebo administrátor v Nastavení → Tarif a platby) fungují znovu beze změny nastavení.
Vytvoření API klíče
Klíč si smí vytvořit každá role.
- Klikněte na svůj avatar vpravo nahoře a zvolte Nastavení.
- V levém menu ve skupině Pro mě otevřete Kalendář a AI asistenti.
- Pod nadpisem K čemu je API klíč klikněte na Potřebuji API klíč. Kdo už nějaký klíč má, vidí místo toho Zobrazit API klíče. Otevře se sekce Osobní API klíče.
- Zadejte název klíče (pro vaši identifikaci, např. „Zapier integrace“).
- Vyberte rozsah — Pouze čtení (předvybrané), nebo Plný přístup.
- Zvolte platnost — Bez omezení (výchozí), nebo 30, 90 či 365 dní.
- Klikněte na Vytvořit klíč.
- Zkopírujte klíč — zobrazí se pouze jednou.
Osobní API klíče najdete v Nastavení → Kalendář a AI asistenti. Společný klíč organizace pro starší integrace je jinde — v Nastavení → API, viz Starý klíč organizace.
Klíč si okamžitě uložte do správce hesel nebo proměnné prostředí. Po zavření rámečku s klíčem ho už nezobrazíte.
Limity
- Každý uživatel může mít maximálně 5 API klíčů.
- Klíč platí do smazání, nebo do konce zvolené platnosti. Vypršelý klíč server odmítne a obnovit ho nejde — vytvoříte nový.
- Klíč člena, který byl v organizaci deaktivován, přestane fungovat okamžitě.
- Každý klíč může poslat nejvýš 120 požadavků za minutu do REST API. Po překročení server vrátí chybu 429 s hlavičkou
Retry-After(za kolik sekund to zkusit znovu). MCP server má vlastní limit 60 požadavků za minutu na klíč. - Nepoužívané klíče doporučujeme smazat.
Použití
API klíč se posílá v HTTP hlavičce Authorization, před klíčem slovo Bearer:
curl -H "Authorization: Bearer cl_abc123def456..." \
https://app.mujvykaz.cz/api/v1/users/me
Klíče začínají předponou cl_. Slovo Bearer se píše s velkým B. Jinou hlavičku server nečte — požadavek s hlavičkou X-API-Key nebo úplně bez klíče skončí chybou 401. Klíče ve tvaru mk_live_… aplikace nikdy nepoužívala.
Oprávnění klíče
API klíč dědí roli uživatele, který ho vytvořil. Přes API platí stejná pravidla jako v aplikaci — co člověk v aplikaci nevidí, nedostane ani přes API:
| Role uživatele | API klíč může |
|---|---|
| Vlastník / Administrátor | Přistupovat ke všem datům organizace |
| Manažer | Pracovat s daty klientů, které spravuje, s hodinami svých lidí a se svými vlastními záznamy; částky jen u svých klientů |
| Účetní | Číst finance, náklady a výkazy celé organizace, vystavovat faktury z reportů, uzavírat měsíce, schvalovat náklady a pracovat s doklady, pravidelnými položkami a importem nákladů; výkazy nezakládá ani neschvaluje |
| HR | Pracovat se svými výkazy, s nepřítomnostmi a nároky na dovolenou, členy týmu a odměnami; peníze projektů a faktury nedostane |
| Člen | Přistupovat ke svým datům |
Jednotlivé oblasti a jejich oprávnění jsou v Endpointech.
Rozsah klíče
Rozsah se uplatní navíc: klíč Pouze čtení jakýkoli zápis odmítne chybou 403 „Tento API klíč má oprávnění pouze pro čtení. Vygenerujte klíč s plným přístupem.“ Čtení rozsah klíče neomezuje — tam rozhoduje jen role.
Dotazy, které nic nemění, smí klíč Pouze čtení položit i přes POST: AI dotaz a náhled importu nákladů.
Připojení Claude
Claude se k MCP serveru nepřihlašuje klíčem, ale tlačítkem Připojit — vytvoří si vlastní přístup, který platí stejná pravidla: roli člověka, tarif organizace a úroveň přístupu zvolenou při připojení (Jen číst, nebo Číst i zapisovat). Připojení vidíte v Nastavení → Kalendář a AI asistenti → Připojené aplikace a tlačítkem Odpojit ho zrušíte. Viz AI asistent.
Starý klíč organizace
V Nastavení → API (karta REST API, vidí a přegeneruje ho jen vlastník a administrátor) je společný klíč celé organizace pro starší integrace. Nemá vlastní identitu ani volbu rozsahu: jede jako administrátor s plným přístupem a v auditním logu se zápis tváří jako zápis vlastníka.
Novější koncové body ho proto odmítají chybou 403 „Tenhle endpoint nepodporuje starý API klíč organizace“. Týká se to například uzávěrek, nepřítomností, odměn, nákladů, klientských reportů, faktur z reportu a zakládání a úprav členů, projektů a klientů. Pro nové integrace vždy použijte osobní klíč.
Zabezpečení
Hashování
API klíče se v databázi ukládají jako HMAC-SHA256 hash se serverovým tajemstvím (pepper). Originální klíč se nikde neukládá — proto ho po vytvoření nemůžete znovu zobrazit, a ani únik databáze nestačí k jeho rekonstrukci.
Ověření klíče
Server při přihlášení hledá otisk klíče, ne klíč samotný, takže z doby odpovědi nejde klíč odhadovat.
Doporučení
- Neukládejte klíče do zdrojového kódu.
- Používejte proměnné prostředí (
MUJVYKAZ_API_KEY). - Vytvářejte oddělené klíče pro různé integrace.
- Klíči na jedno použití dejte omezenou platnost.
- Smažte klíč ihned, pokud ho omylem zveřejníte.
Správa klíčů
V sekci Osobní API klíče (Nastavení → Kalendář a AI asistenti) vidíte u každého klíče:
| Údaj | Popis |
|---|---|
| Název | Vámi zvolený popis |
| Rozsah | Štítek Pouze čtení, nebo Plný přístup |
| Vytvořen | Datum vytvoření |
| Použit | Datum posledního použití (u nepoužitého klíče se nezobrazuje) |
| Platí do | Datum konce platnosti (jen u klíče s omezenou platností) |
Vypršelý klíč má odznak Vypršel. Klíč, kterým se nikdo nepřihlásil přes 90 dní, má odznak Nepoužívaný — funguje dál, jen ho nejspíš můžete zrušit.
Samotný klíč se po vytvoření už nikde neukazuje — v seznamu je jen jeho název.
Kliknutím na Odvolat klíč okamžitě přestane fungovat. Akci nelze vrátit.
Když se přihlášení nepovede
| Odpověď | Co znamená |
|---|---|
| 401 „Missing or invalid Authorization header“ | Chybí hlavička Authorization: Bearer … (nebo je jinak napsaná) |
| 401 „Invalid API key“ | Klíč je neplatný nebo odvolaný |
| 401 „API key expired“ | Klíči vypršela platnost — vytvořte nový |
| 403 „User account is deactivated“ | Člen, kterému klíč patří, je deaktivovaný |
| 403 „API a MCP jsou od tarifu Starter…“ | Organizace je na tarifu Free; po přechodu na vyšší tarif klíč funguje zase |
| 403 „Tento API klíč má oprávnění pouze pro čtení…“ | Klíč má rozsah Pouze čtení, a požadavek zapisuje |
| 429 | Překročený limit požadavků — počkejte podle hlavičky Retry-After |