## Čo je API token API token `(APPLICATION_TOKEN)` je tajný kľúč, ktorým sa vaša aplikácia prihlasuje k BulkGate API. Spolu s [Application ID](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/) `(APPLICATION_ID)` tvorí kompletné prístupové údaje — bez oboch API požiadavku odmietne. Token je náhodný reťazec s dĺžkou 50 znakov zložený z číslic a malých aj veľkých písmen. V databáze je uložený zašifrovane a nemá dobu platnosti — platí, kým ho sami neobnovíte, nezakážete alebo nezmažete. Jeden token vznikne automaticky vo chvíli, keď API vytvoríte. Ďalšie si môžete kedykoľvek [pridať](#ako-pridat-dalsi-token) — napríklad pre každý server alebo pre každé prostredie zvlášť, aby sa dal jeden z nich odvolať bez dopadu na ostatné. > [!CAUTION] > Token nikomu neprezrádzajte a neukladajte ho do verejného repozitára. Ktokoľvek s > tokenom a Application ID môže odosielať správy na váš účet. Ak máte podozrenie, že > sa k nemu niekto dostal, token [obnovte](#ako-token-obnovit) alebo > [zmažte](#ako-token-zmazat). ## Kde token nájdem 1. V menu portálu kliknite na `Moduly a API` 2. V časti `Moje API a Moduly` kliknite na kartu svojej aplikácie 3. Zostaňte na karte `Nastavenie` a nájdite časť `Prihlasovacie údaje` Je tu `Application ID` a pod ním, za podnadpisom `Application Token`, zoznam tokenov danej aplikácie. Token sa nikdy nezobrazuje priamo — vidíte len jeho prvé a posledné štyri znaky, zvyšok je nahradený hviezdičkami. Stav tokenu spoznáte podľa ikony vľavo: zelená znamená povolený token, červená zakázaný. Zakázaný token je navyše prečiarknutý. Vpravo pri každom tokene je tlačidlo s prečiarknutým okom na jeho zobrazenie; ostatné akcie sú skryté pod ikonou troch bodiek `Viac možností`. ![Časť Prihlasovacie údaje so zoznamom tokenov](docs:api-tokens/token-list_cs) ## Ako si token zobraziť a skopírovať 1. Kliknite na ikonu prečiarknutého oka pri tokene, ktorý chcete zobraziť 2. Otvorí sa okno `Ukážte token` s upozornením, aby ste skontrolovali svoje okolie 3. Zadajte heslo k svojmu účtu a kliknite na `Pokračovať` 4. Token sa vypíše v plnom znení; ikona sa zmení na `Kopírovať`, ktorým ho dostanete do schránky ![Okno Ukážte token s výzvou na zadanie hesla](docs:api-tokens/token-show_cs) > [!NOTE] > Odhalenie tokenu platí len do opätovného načítania stránky. Po obnovení sa token znova > zamaskuje a na ďalšie zobrazenie musíte znova zadať heslo. ## Ako pridať ďalší token 1. V časti `Prihlasovacie údaje` kliknite dole na `Pridať token` 2. Zadajte heslo k svojmu účtu 3. Kliknite na `Pridať` Portál potvrdí hláškou `Token bol vytvorený` a nový token rovno vypíše v plnom znení — skopírujte si ho hneď, po opätovnom načítaní stránky sa zamaskuje ako ostatné. Počet tokenov pri jednej aplikácii nie je nijako obmedzený. ## Ako token obnoviť Obnovenie prepíše existujúci token novým. V zozname zostane na svojom mieste, len s novou hodnotou. 1. Pri tokene kliknite na `Viac možností` a zvoľte `Vygenerujte nový` 2. Zadajte heslo k svojmu účtu 3. Kliknite na `Vygenerujte nový` ![Ponuka Viac možností s voľbami Vygenerujte nový, Zakázať a Zmazať](docs:api-tokens/token-menu_cs) Portál potvrdí hláškou `Token bol obnovený`. > [!WARNING] > Starý token prestane platiť okamžite. Každá integrácia, ktorá ho používala, začne > dostávať chybu — nový token do nej doplňte hneď. ## Ako token zakázať a znova povoliť Zákaz tokenu je vratná alternatíva mazania: token zostane v zozname, ale nedá sa ním autentifikovať. 1. Pri tokene kliknite na `Viac možností` 2. Zvoľte `Zakázať`, pri už zakázanom tokene `Povoliť` 3. Voľbu potvrďte v okne, ktoré sa otvorí Portál potvrdí hláškou `Token bol zakázaný`, respektíve `Token bol povolený`. Pri tejto akcii sa heslo nezadáva. ## Ako token zmazať 1. Pri tokene kliknite na `Viac možností` a zvoľte `Zmazať` 2. V okne `Zmazať token` potvrďte tlačidlom `Zmazať` Portál potvrdí hláškou `Token bol odstránený`. Ani pri tejto akcii sa heslo nezadáva. > [!CAUTION] > Zmazanie je nevratné — token už nepôjde obnoviť ani zobraziť. Ak chcete len > dočasne zablokovať prístup, použite radšej [zákaz tokenu](#ako-token-zakazat-a-znova-povolit). Všetky tokeny aplikácie zaniknú aj vo chvíli, keď zmažete samotnú aplikáciu. ## Ako sa token posiela do API Application ID a token odovzdáte v požiadavke ako parametre `application_id` a `application_token` — buď v tele požiadavky, alebo v query stringu. Druhou možnosťou je [podpísať tokenom JWT](#ako-token-pouzit-v-podpisanom-jwt) a poslať ho v hlavičke. Neplatný, zakázaný alebo zmazaný token skončí odpoveďou s HTTP kódom `401` a typom chyby `unknown_identity`. Rovnakú odpoveď dostanete aj vtedy, keď je zakázaná samotná aplikácia alebo keď má nastavené povolené IP adresy a požiadavka príde odinakiaľ. Prehľad ostatných chýb nájdete na stránke [Typy chýb API](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/). ## Ako token použiť v podpísanom JWT Namiesto posielania tokenu v každej požiadavke ním môžete podpísať JWT a do API poslať ten. Token tak zostane na vašej strane — po sieti ide len podpis, ktorý z neho vznikol. Hotový JWT vložte do hlavičky `Authorization`: ```http POST /api/1.0/simple/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json Authorization: Bearer ``` Aby ho API prijalo, musí mať takúto podobu: | Časť | Obsah | |:--|:--| | Hlavička | `{"alg":"HS256","typ":"JWT"}` — iný algoritmus ani typ API neprijme | | Payload | `application_id` s [Application ID](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/) vašej aplikácie | | Podpis | HMAC-SHA256 z hlavičky a payloadu, kde kľúčom je API token | Payload s aplikáciou číslo 39238 teda vyzerá takto: ```json { "application_id": 39238 } ``` > [!NOTE] > Keď pošlete JWT, `application_id` ani `application_token` už v parametroch > požiadavky uvádzať nemusíte — API si identitu vezme z payloadu. Platnosť jednotlivého JWT môžete obmedziť poľom `expire` v `application_parameters`. Hodnotou je unixový čas v sekundách, po ktorého dosiahnutí JWT prestane platiť: ```json { "application_id": 39238, "application_parameters": { "expire": 1800000000 } } ``` Bez tohto poľa platí JWT tak dlho, kým platí token, ktorým je podpísaný. Hodí sa preto tam, kde JWT odovzdávate ďalej — podpíšete ho s krátkou platnosťou a token pritom zostane len u vás. Podpis sa overuje voči všetkým povoleným tokenom aplikácie, takže JWT môžete podpísať ktorýmkoľvek z nich. Zakázaný ani zmazaný token neprejde — platí preň to isté, čo je popísané vyššie: odpoveď s HTTP kódom `401` a typom chyby `unknown_identity`.