API kľúče
API kľúče umožňujú integráciám -- automatizačným nástrojom ako n8n alebo Zapier, skriptom na reporty či vlastným aplikáciám -- používať REST API EOS Hub vo vašom mene. Každý používateľ spravuje svoje kľúče v Nastavenia > API kľúče.
INFO
Kľúče s prístupom Čítanie a zápis môžu meniť všetko, čo vám vaše roly dovoľujú vo webovej aplikácii -- dáta tímu ako úlohy, problémy, Rocks, Scorecard a stretnutia (pozri Zápis dát) a Vlastníci a Administrátori organizácie aj jej nastavenia, členov a tímy (pozri Správa organizácie). Samotné kľúče sa spravujú len tu, vo webovej aplikácii.
Ako kľúč funguje
Kľúč je dlhý tajný reťazec, ktorý začína na ak_. Integrácia ho posiela s každou požiadavkou a EOS Hub požiadavku spracuje tak, akoby prišla od vás:
- Platia vaše aktuálne roly. Kľúč vidí presne to, čo vidíte vy vo webovej aplikácii, vo všetkých organizáciách, do ktorých patríte. Keď sa vaše roly zmenia, kľúč sa im okamžite prispôsobí -- ak vás odoberú z organizácie alebo tímu, kľúč k nim hneď stratí prístup.
- Prístup kľúča môže vaše práva len zúžiť. Kľúč Len čítanie nemôže nič zmeniť, ani keď ste Administrátor tímu.
- Pozastavené organizácie zostávajú čitateľné, rovnako ako vo webovej aplikácii.
Vytvorenie kľúča
- Otvorte Nastavenia a posuňte sa ku karte API kľúče.
- Kliknite na Vytvoriť kľúč.
- Zadajte Názov, podľa ktorého kľúč neskôr spoznáte -- typicky integráciu, ktorá ho bude používať, napríklad n8n reporty.
- Zvoľte Prístup:
- Len čítanie -- môže čítať všetko, čo vidíte vy.
- Čítanie a zápis -- môže aj vytvárať a meniť dáta podľa vašej roly.
- Zvoľte Platnosť: 30 dní, 90 dní (predvolené), 365 dní alebo Bez obmedzenia.
- Kliknite na Vytvoriť kľúč.
Skopírujte si kľúč -- zobrazí sa iba raz
Po vytvorení dialóg zobrazí celý kľúč s tlačidlom Kopírovať. Kľúč sa zobrazí iba v tejto chvíli. Hneď si ho skopírujte a uložte -- do úložiska prihlasovacích údajov integrácie alebo do správcu hesiel.
EOS Hub si ukladá len odtlačok (hash) kľúča, nikdy samotný kľúč, takže vám ho nikto -- ani prevádzkovateľ platformy -- nemôže znovu zobraziť. Ak kľúč stratíte, odvolajte ho a vytvorte nový.
WARNING
Dialóg zatvorte až po uložení kľúča. Po zatvorení sa kľúč už zobraziť nedá.
Zoznam kľúčov
Karta API kľúče zobrazuje všetky vaše kľúče od najnovšieho:
| Stĺpec | Popis |
|---|---|
| Názov | Názov, ktorý ste kľúču dali, s jeho viditeľným začiatkom, napr. ak_k3m7q2xa_…, aby ste ho vedeli spárovať s kľúčom uloženým v integrácii |
| Oprávnenia | Čítanie, Zápis a pri kľúčoch platformy Platforma |
| Naposledy použitý | Kedy kľúč naposledy použila integrácia (aktualizuje sa najviac raz za minútu), alebo Zatiaľ nepoužitý |
| Platnosť do | Dátum expirácie alebo Nikdy |
| Stav | Aktívny, Expirovaný alebo Odvolaný |
Expirované a odvolané kľúče zostávajú v zozname pre prehľad, ale už nefungujú.
Odvolanie kľúča
Kliknite na ikonu koša pri aktívnom kľúči a potvrďte. Integrácie, ktoré kľúč používajú, okamžite prestanú fungovať. Odvolanie sa nedá vrátiť -- ak chcete integráciu znovu pripojiť, vytvorte nový kľúč.
Kľúč odvolajte, keď:
- integráciu už nepoužívate,
- kľúč mohol uniknúť (dostal sa do repozitára, vložili ste ho do chatu, poslali e-mailom …),
- osoba alebo služba, ktorá kľúč mala, už nemá mať prístup.
Obmedzenia
- Každý používateľ môže mať najviac 10 aktívnych kľúčov. Po dosiahnutí limitu je Vytvoriť kľúč neaktívne -- najprv odvolajte kľúč, ktorý už nepotrebujete. Expirované a odvolané kľúče sa nezapočítavajú.
- Kľúče sa dajú vytvoriť a odvolať len v prihlásenej webovej aplikácii. Kľúčom sa nikdy nedajú vytvárať ani odvolávať iné kľúče, takže uniknutý kľúč sa nemôže sám nahradiť ani vás zablokovať.
- Každý kľúč smie poslať 120 požiadaviek za minútu -- pozri Limit požiadaviek.
Bezpečnosť kľúčov
Kľúč dáva prístup ku všetkému, čo v EOS Hub vidíte. Zaobchádzajte s ním ako s heslom:
- Uprednostnite Len čítanie. Čítanie a zápis zvoľte len pre integrácie, ktoré naozaj potrebujú meniť dáta.
- Zvoľte krátku platnosť. 30 alebo 90 dní obmedzí škody, ak kľúč nepozorovane unikne. Bez obmedzenia používajte len pre dlhodobé integrácie, ktoré sledujete.
- Jeden kľúč na integráciu. Samostatné kľúče sa dajú odvolať nezávisle, majú vlastný čas Naposledy použitý aj vlastný limit požiadaviek.
- Nikdy nedávajte kľúče do zdrojového kódu ani tam, kde ich môžu čítať iní. Uchovávajte ich v premenných prostredia alebo v úložisku tajomstiev.
- Sledujte Naposledy použitý. Kľúč použitý vtedy, keď to nečakáte, mohol uniknúť -- odvolajte ho.
- Odvolajte kľúče, ktoré už nepotrebujete.
Kľúče platformy
Prevádzkovatelia platformy (systémová rola SUPERADMIN) vidia v dialógu vytvorenia navyše voľbu Správa platformy. Kľúč platformy môže navyše používať endpointy na správu platformy -- organizácie, kontá, API kľúče používateľov a nastavenia AI.
Keďže taký kľúč ovláda všetky organizácie, všetkých používateľov aj nastavenia AI:
- jeho platnosť môže byť najviac 30 alebo 90 dní -- 365 dní ani Bez obmedzenia sa neponúkajú;
- pre správu platformy prestane fungovať, keď jeho vlastník prestane byť prevádzkovateľom platformy;
- v zozname kľúčov je označený červeným štítkom Platforma.
DANGER
Kľúče platformy držte v tajnosti, s krátkou platnosťou a mimo zdieľaných nástrojov. Odvolajte ich hneď, ako je úloha, pre ktorú vznikli, hotová.
Čo vidí prevádzkovateľ platformy
Prevádzkovateľ platformy vám môže pomôcť, keď kľúč mohol uniknúť. V Správe platformy > Používatelia ukazuje stĺpec API kľúče počet aktívnych kľúčov každého používateľa. Kliknutím na počet sa otvorí zoznam kľúčov používateľa -- názov, viditeľný začiatok, oprávnenia, posledné použitie, platnosť a stav -- kde môže prevádzkovateľ odvolať ktorýkoľvek aktívny kľúč.
Samotné kľúče prevádzkovateľ nikdy nevidí (neukladajú sa) a nemôže vytvárať kľúče za iných.
Ďalšie kroky
- REST API -- autentifikácia, endpointy, stránkovanie a chyby
- Správa používateľov -- roly v organizácii a tíme, s ktorými kľúč koná
- Nastavenia organizácie a platforma -- správa platformy