## Co je API token API token `(APPLICATION_TOKEN)` je tajný klíč, kterým se vaše aplikace přihlašuje k BulkGate API. Spolu s [Application ID](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/administrace-api/) `(APPLICATION_ID)` tvoří kompletní přístupové údaje — bez obojího API požadavek odmítne. Token je náhodný řetězec o délce 50 znaků složený z číslic a malých i velkých písmen. V databázi je uložený zašifrovaně a nemá dobu platnosti — platí, dokud ho sami neobnovíte, nezakážete nebo nesmažete. Jeden token vznikne automaticky ve chvíli, kdy API vytvoříte. Další si můžete kdykoli [přidat](#jak-pridat-dalsi-token) — třeba pro každý server nebo pro každé prostředí zvlášť, aby se dal jeden z nich odvolat bez dopadu na ostatní. > [!CAUTION] > Token nikomu nesdělujte a neukládejte ho do veřejného repozitáře. Kdokoli s > tokenem a Application ID může odesílat zprávy na váš účet. Máte-li podezření, že > se k němu někdo dostal, token [obnovte](#jak-token-obnovit) nebo > [smažte](#jak-token-smazat). ## Kde token najdu 1. V menu portálu klikněte na `Moduly a API` 2. V části `Moje API a Moduly` klikněte na kartu své aplikace 3. Zůstaňte na kartě `Nastavení` a najděte část `Přihlašovací údaje` Je tu `Application ID` a pod ním, za podnadpisem `Application Token`, seznam tokenů dané aplikace. Token se nikdy nezobrazuje rovnou — vidíte jen jeho první a poslední čtyři znaky, zbytek je nahrazený hvězdičkami. Stav tokenu poznáte podle ikony vlevo: zelená znamená povolený token, červená zakázaný. Zakázaný token je navíc přeškrtnutý. Vpravo u každého tokenu je tlačítko s přeškrtnutým okem pro jeho zobrazení; ostatní akce jsou schované pod ikonou tří teček `Více možností`. ![Část Přihlašovací údaje se seznamem tokenů](docs:api-tokens/token-list_cs) ## Jak si token zobrazit a zkopírovat 1. Klikněte na ikonu přeškrtnutého oka u tokenu, který chcete zobrazit 2. Otevře se okno `Zobrazit token` s upozorněním, ať zkontrolujete své okolí 3. Zadejte heslo ke svému účtu a klikněte `Pokračovat` 4. Token se vypíše v plném znění; ikona se změní na `Kopírovat`, kterým ho dostanete do schránky ![Okno Zobrazit token s výzvou k zadání hesla](docs:api-tokens/token-show_cs) > [!NOTE] > Odhalení tokenu platí jen do znovunačtení stránky. Po obnovení se token zase > zamaskuje a pro další zobrazení musíte znovu zadat heslo. ## Jak přidat další token 1. V části `Přihlašovací údaje` klikněte dole na `Přidat token` 2. Zadejte heslo ke svému účtu 3. Klikněte `Přidat` Portál potvrdí hláškou `Token byl vytvořen` a nový token rovnou vypíše v plném znění — zkopírujte si ho hned, po znovunačtení stránky se zamaskuje jako ostatní. Počet tokenů u jedné aplikace není nijak omezený. ## Jak token obnovit Obnovení přepíše stávající token novým. V seznamu zůstane na svém místě, jen s novou hodnotou. 1. U tokenu klikněte na `Více možností` a zvolte `Vygenerujte nový` 2. Zadejte heslo ke svému účtu 3. Klikněte `Vygenerujte nový` ![Nabídka Více možností s volbami Vygenerujte nový, Zakázat a Smazat](docs:api-tokens/token-menu_cs) Portál potvrdí hláškou `Token byl obnoven`. > [!WARNING] > Starý token přestane platit okamžitě. Každá integrace, která ho používala, začne > dostávat chybu — nový token do ní doplňte hned. ## Jak token zakázat a znovu povolit Zákaz tokenu je vratná alternativa mazání: token zůstane v seznamu, ale nedá se jím autentizovat. 1. U tokenu klikněte na `Více možností` 2. Zvolte `Zakázat`, u už zakázaného tokenu `Povolit` 3. Volbu potvrďte v okně, které se otevře Portál potvrdí hláškou `Token byl zakázán`, respektive `Token byl povolen`. Na tuhle akci se heslo nezadává. ## Jak token smazat 1. U tokenu klikněte na `Více možností` a zvolte `Smazat` 2. V okně `Smazat token` potvrďte tlačítkem `Smazat` Portál potvrdí hláškou `Token byl odstraněn`. Ani na tuhle akci se heslo nezadává. > [!CAUTION] > Smazání je nevratné — token už nepůjde obnovit ani zobrazit. Pokud chcete jen > dočasně zablokovat přístup, použijte raději [zákaz tokenu](#jak-token-zakazat-a-znovu-povolit). Všechny tokeny aplikace zaniknou také ve chvíli, kdy smažete samotnou aplikaci. ## Jak se token posílá do API Application ID a token předáte v požadavku jako parametry `application_id` a `application_token` — buď v těle požadavku, nebo v query stringu. Druhou možností je [podepsat tokenem JWT](#jak-token-pouzit-v-podepsanem-jwt) a poslat ho v hlavičce. Neplatný, zakázaný nebo smazaný token skončí odpovědí s HTTP kódem `401` a typem chyby `unknown_identity`. Stejnou odpověď dostanete i tehdy, když je zakázaná samotná aplikace nebo když má nastavené povolené IP adresy a požadavek přijde odjinud. Přehled ostatních chyb najdete na stránce [Typy errorů API](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/). ## Jak token použít v podepsaném JWT Místo posílání tokenu v každém požadavku jím můžete podepsat JWT a do API poslat ten. Token tak zůstane na vaší straně — po síti jde jen podpis, který z něj vznikl. 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 přijalo, musí mít tuhle podobu: | Část | Obsah | |:--|:--| | Hlavička | `{"alg":"HS256","typ":"JWT"}` — jiný algoritmus ani typ API nepřijme | | Payload | `application_id` s [Application ID](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/administrace-api/) vaší aplikace | | Podpis | HMAC-SHA256 z hlavičky a payloadu, kde klíčem je API token | Payload s aplikací číslo 39238 tedy vypadá takhle: ```json { "application_id": 39238 } ``` > [!NOTE] > Když pošlete JWT, `application_id` ani `application_token` už v parametrech > požadavku uvádět nemusíte — API si identitu vezme z payloadu. Platnost jednotlivého JWT můžete omezit polem `expire` v `application_parameters`. Hodnotou je unixový čas v sekundách, po jehož dosažení JWT přestane platit: ```json { "application_id": 39238, "application_parameters": { "expire": 1800000000 } } ``` Bez tohoto pole platí JWT tak dlouho, dokud platí token, kterým je podepsaný. Hodí se proto tam, kde JWT předáváte dál — podepíšete ho krátkou platností a token přitom zůstane jen u vás. Podpis se ověřuje proti všem povoleným tokenům aplikace, takže JWT můžete podepsat kterýmkoli z nich. Zakázaný ani smazaný token neprojde — platí pro něj totéž, co je popsané výš: odpověď s HTTP kódem `401` a typem chyby `unknown_identity`.