API tokeny

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 (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 — třeba pro každý server nebo pro každé prostředí zvlášť, aby se dal jeden z nich odvolat bez dopadu na ostatní.

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í.

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

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ý

Portál potvrdí hláškou Token byl obnoven.

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á.

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 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.

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:

Aby ho API přijalo, musí mít tuhle podobu:

Payload s aplikací číslo 39238 tedy vypadá takhle:

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:

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.