API tokeny

Č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 (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ť — napríklad pre každý server alebo pre každé prostredie zvlášť, aby sa dal jeden z nich odvolať bez dopadu na ostatné.

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

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

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ý

Portál potvrdí hláškou Token bol obnovený.

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.

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

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:

Aby ho API prijalo, musí mať takúto podobu:

Payload s aplikáciou číslo 39238 teda vyzerá takto:

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ť:

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.