Osobný prístupový token (PAT) – čo to je a ako ho používať#

Čo je osobný prístupový token (PAT)?#

PAT (z anglického Personal Access Token, slovensky osobný prístupový token) je dlhý náhodný reťazec, ktorý slúži ako alternatíva k heslu na prístup k Mergado API. Token reprezentuje vás a vaše oprávnenia – keď ho niekomu (alebo nejakej aplikácii) odovzdáte, môže za vás v Mergade vykonávať akcie v rozsahu, ktorý ste tokenu povolili.

Skratku PAT používame preto, že je to štandardný termín naprieč odvetvím (GitHub, GitLab, Atlassian a i.).

PAT na rozdiel od hesla:

  • Má obmedzený rozsah (scopes) – vyberiete, čo konkrétne smie token robiť (napr. len čítať projekty, nie mazať).
  • Má voliteľnú platnosť – môžete nastaviť, kedy token prestane fungovať.
  • Dá sa kedykoľvek zneplatniť bez nutnosti meniť heslo.
  • Nedá sa pomocou neho meniť nastavenie účtu (zmena hesla, e-mailu, fakturácie) – na to sa musíte prihlásiť štandardným spôsobom.
  • Nesprístupňuje vaše heslo tretej strane, aj keď token odovzdáte.

PAT je určený na prístup k Mergado Editor API. Tokenom sa nedá prihlasovať do ďalších služieb Mergada (Mergado Fórum, Mergado Store a pod.).

Kedy budem PAT potrebovať?#

Typické scenáre:

  • Prepojenie Mergada s AI agentmi typu ChatGPT, Claude alebo Cursor cez Mergado MCP server. Návod nájdete v článku Prepojenie Mergada s AI agentmi.
  • Vlastné skripty a automatizácie – napr. pravidelný export dát, hromadné úpravy projektov, integrácia do interných systémov.
  • Vývoj a testovanie vlastných aplikácií nad Mergado API.
  • Prepojenie s no-code nástrojmi typu Zapier, Make, n8n alebo Gumloop.

Ako vygenerovať PAT?#

  1. Prihláste sa do Mergado Editora.

  2. V pravom hornom rohu kliknite na svoj profil → API a prístupy.

  3. Kliknite na tlačidlo + Vytvoriť token.

  4. Pomenujte token popisom, podľa ktorého spoznáte, kde je použitý – napr. „Claude Desktop“, „Export skript pre účtovníčku“. Až budete tokeny neskôr spravovať, názov je hlavné vodidlo, ako ich od seba odlíšiť.

  5. Nastavte platnosť tokenu. Voľby:

    • 7 dní
    • 30 dní
    • 90 dní
    • 365 dní
    • Nikdy (token bude platiť, kým ho ručne nezneplatníte)

    Pre tokeny v automatizácii odporúčame nastaviť konkrétnu platnosť (napr. 90 dní) – pravidelná obnova znižuje dopad prípadného úniku tokenu. Na vývoj a testovanie stačí krátka platnosť (7 dní).

  6. Vyberte oprávnenia (scopes) – viď Oprávnenia

  7. Kliknite na Vytvoriť.

  8. Skopírujte token a uložte ho na bezpečné miesto (správca hesiel, šifrovaný súbor). Po opustení stránky už token znova nezobrazíme – ak ho stratíte, musíte vytvoriť nový.

Token má prefix mergado_pat_ nasledovaný 60 náhodnými znakmi, napr. mergado_pat_aec7bb21ff4b2c09b156cd3130b4eef0daf69ea2e1e0d62c23472626aa7e72314fdbb53896b2fd8046c5.

Tip: V zozname tokenov uvidíte tzv. náhľad tokenu vo formáte mergado_pat_***8046c5, kde posledných 6 znakov zodpovedá koncovke skutočného tokenu. Môžete tak rýchlo overiť, ktorý token je ktorý, bez toho, aby ste ho museli mať poruke.

Token je citlivý údaj – správajte sa k nemu ako k heslu. Ktokoľvek s tokenom má v Mergade rovnaké oprávnenia ako vy v rozsahu udelených scopes.

Oprávnenia (scopes)#

Pri tvorbe tokenu vyberáte konkrétne oprávnenia zaškrtávacími poľami. Oprávnenia sú zoskupené do logických celkov (Používateľ, E-shop, Projekt), aby ste sa v nich ľahšie zorientovali.

Odporúčanie: Udeľte tokenu len tie oprávnenia, ktoré daná aplikácia skutočne potrebuje. Ak napríklad skript len číta dáta z projektu, nepotrebuje práva na zápis ani mazanie. Tomuto princípu sa hovorí princíp najmenších oprávnení (least privilege).

Používateľ#

Oprávnenia týkajúce sa vášho používateľského účtu a informácií o vás.

Oprávnenie Čo umožňuje
Čítanie dát používateľa Prístup k informáciám o používateľovi – meno, username, e-mail, dátum registrácie a pod.
Čítanie e-shopov používateľa Zobrazenie zoznamu e-shopov a ich detailov, ku ktorým má používateľ prístup (ako Vlastník, Čítanie alebo Zápis).
Čítanie správ používateľa Čítanie notifikácií používateľa – systémové správy aj správy od iných aplikácií.
Zasielanie správ pre používateľa Odosielanie notifikácií používateľovi (e-mail a frontend notifikácie).
Čítanie zapnutých rozšírení u používateľa Prístup k zoznamu zapnutých rozšírení u používateľa.

E-shop#

Oprávnenia k dátam konkrétneho e-shopu.

Oprávnenie Čo umožňuje
Čítanie dát e-shopu Prístup k informáciám o e-shope – názov, doména, počet exportovaných položiek, používatelia s prístupom a pod.
Čítanie projektov v e-shope Prístup ku všetkým projektom (exportom) e-shopu a ich základným informáciám. Nezahŕňa prístup k pravidlám, výberom, elementom a pod.
Čítanie dát služieb prepojených s e-shopom cez Keychain Čítanie dát zo služieb napojených cez Keychain (napr. Heureka, Google Ads…).
Úprava dát v službách prepojených s e-shopom cez Keychain Zápis a úprava dát v službách napojených cez Keychain.
Čítanie štatistík e-shopu Prístup k štatistikám e-shopu. Štatistiky musia byť vopred nazbierané – vyžaduje vyplnenie dát v Keychain.
Čítanie zdrojov štatistík e-shopu Prístup k zoznamu zdrojov, z ktorých sú štatistiky zbierané.
Čítanie Google Analytics e-shopu Čítanie dát z Google Analytics e-shopu. Používateľ musí najprv udeliť oprávnenie cez Keychain.
Čítanie správ e-shopu Čítanie notifikácií odoslaných členom e-shopu vrátane systémových správ.
Zasielanie správ pre e-shop Odosielanie notifikácií členom e-shopu.
Čítanie zapnutých rozšírení u e-shopu Prístup k zoznamu zapnutých rozšírení u e-shopu.

Projekt#

Oprávnenia k jednotlivým projektom (exportom) v rámci e-shopu. Táto skupina je najrozsiahlejšia – projekt obsahuje pravidlá, výbery, produkty, štatistiky atď. a každá z týchto vrstiev má vlastné oprávnenia na čítanie a zápis.

Oprávnenie Čo umožňuje
Čítanie dát projektu Prístup k základným informáciám o projekte – názov, URL feedu, počet exportovaných položiek a pod.
Úprava dát projektu Úprava projektu. Nezahŕňa vytváranie pravidiel, výberov, elementov a pod.
Čítanie elementov Zobrazenie elementov projektu – názov, viditeľnosť a ďalšie vlastnosti.
Úprava elementov Vytváranie, úprava a mazanie elementov v projekte.
Čítanie výberov Čítanie výberov (queries) v projekte. Výbery sú tvorené používateľom alebo aplikáciou.
Úprava výberov Čítanie, mazanie a vytváranie výberov. Výbery možno potom použiť na filtrovanie produktov.
Čítanie pravidiel Zobrazenie všetkých pravidiel v projekte.
Úprava pravidiel Mazanie, úprava a vytváranie nových pravidiel v projekte.
Čítanie premenných Zobrazenie premenných projektu – názov, typ a ďalšie informácie.
Úprava premenných Mazanie, úprava a vytváranie premenných v projekte.
Čítanie produktov projektu Zobrazenie produktov projektu. Postačuje aj na filtrovanie produktov pomocou výberov.
Zápis do produktov projektu Mazanie, úprava a vytváranie produktov v projekte.
Čítanie štatistík projektu Prístup k štatistikám projektu a pokročilej analytike.
Čítanie Google Analytics projektu Čítanie dát z GA filtrovaných podľa výstupného formátu projektu (napr. len dáta z Heureky).
Čítanie histórie spracovania projektu Zobrazenie prebehnutých úloh – import z XML, aplikácia pravidiel, export do XML (vrátane automatických).
Spúšťanie nových spracovaní projektu Spúšťanie úloh – import z XML, aplikácia pravidiel, export do XML.
Čítanie auditov feedu Čítanie výsledkov auditu XML feedu projektu – nájdené problémy, chýbajúce elementy a pod.
Spúšťanie auditov feedu Spustenie novej validácie (auditu) XML feedu projektu.
Čítanie histórie projektu Prístup k logom projektu – vykonané úlohy aj sťahovanie výstupného XML feedu tretími stranami.
Čítanie zapnutých rozšírení u projektu Prístup k zoznamu zapnutých rozšírení u projektu.

Pre vývojárov: technické názvy (ID) jednotlivých scopes v API formáte (napr. project.rules.write) nájdete v API dokumentácii OAuth scopes.

V zozname tokenov pri každom riadku vidíte počet udelených oprávnení a kliknutím na Zobraziť ich môžete rozbaliť ako tagy.

Ako token použiť?#

Token sa posiela v hlavičke HTTP požiadavky ako Bearer token:

Authorization: Bearer <váš-token>

Príklad volania API cez curl:

curl -H "Authorization: Bearer mergado_pat_..." \
     https://api.mergado.com/me

Kompletný popis všetkých endpointov nájdete v API dokumentácii:

Bezpečnosť a správa tokenov#

Čo robiť#

  • Token uložte do správcu hesiel alebo do šifrovanej konfigurácie (napr. premenná prostredia, secret manager).
  • Pre každú aplikáciu/integráciu vytvorte samostatný token s vlastným názvom. Ľahšie sa potom zneplatní konkrétna integrácia bez dopadu na ostatné.
  • Tokenu udeľte len tie oprávnenia, ktoré potrebuje (princíp najmenších oprávnení).
  • Pravidelne prechádzajte zoznam aktívnych tokenov a zneplatňujte tie, ktoré už nepoužívate.
  • Pre tokeny v automatizácii nastavte platnosť 90 dní a token periodicky obnovujte.

Čo nerobiť#

  • Necommitujte token do Gitu ani do žiadneho repozitára. Ak k tomu omylom dôjde, token okamžite zneplatnite – história Gitu je verejne prístupná aj po zmazaní súboru.
  • Neposielajte token cez e-mail, Slack, Teams ani iné chat aplikácie v plain texte.
  • Nezdieľajte jeden token medzi viacerými ľuďmi alebo aplikáciami.

Čo robiť pri kompromitácii#

Ak máte podozrenie, že sa vám token dostal do nepovolaných rúk (napr. omylom zverejnený v repozitári, screenshote, podozrivá aktivita na účte):

  1. Okamžite choďte do API a prístupy a token zneplatnite (ikona koša v zozname).
  2. Vytvorte nový token a aktualizujte ho vo všetkých integráciách, kde bol použitý.

FAQ#

Stratil som token, čo teraz?#

Token už znova nezobrazíme. Vytvorte nový a aktualizujte ho v aplikácii, kde bol použitý. Starý token odporúčame zneplatniť, nech sa nedá zneužiť, ak ho niekto neskôr nájde.

Koľko tokenov môžem mať?#

Počet osobných prístupových tokenov na jedného používateľa nie je aktuálne obmedzený. Odporúčame však vytvárať samostatný token pre každú integráciu – ľahšie sa potom spravujú a v prípade potreby možno konkrétnu integráciu odpojiť zneplatnením jediného tokenu.

Ako dlho je token platný?#

Tak dlho, ako ste si nastavili pri jeho vytvorení – 7, 30, 90, 365 dní, alebo Nikdy. Aktuálny dátum vypršania vidíte v zozname tokenov v stĺpci Vyprší. Po vypršaní token prestane fungovať a musíte si vytvoriť nový.

API mi vracia 401 Unauthorized. Čo s tým?#

  • Skontrolujte, že token kopírujete celý a bez medzier na začiatku/konci.
  • Skontrolujte formát hlavičky: Authorization: Bearer <token> (slovo Bearer sa oddeľuje medzerou).
  • Token mohol byť zneplatnený alebo expiroval – v zozname tokenov skontrolujte stĺpec Vyprší.
  • Ak token chýba v zozname úplne, bol zmazaný – vytvorte nový.

API mi vracia 403 Forbidden. Čo s tým?#

Token je platný, ale nemá oprávnenie na danú akciu. Skontrolujte v zozname tokenov jeho oprávnenia (stĺpec Oprávnenia → Zobraziť) a v prípade potreby vytvorte nový s rozšírenými scopes. Existujúci token rozšíriť nemožno – z bezpečnostných dôvodov musíte vytvoriť nový.

Môžem token použiť na prihlásenie do Mergado Fóra alebo Mergado Store?#

Nie. PAT je určený výhradne pre Mergado Editor API. Do ostatných služieb Mergada sa prihlasujte štandardne cez Mergado účet.

Môžem PAT používať vo svojej aplikácii, ktorú poskytujem klientom?#

Nie. PAT reprezentuje konkrétneho používateľa. Ak vyvíjate aplikáciu, ktorú budú používať zákazníci Mergada, použite OAuth flow – každý používateľ sa autorizuje sám pod svojím účtom. Viac v API dokumentácii.

Súvisiace odkazy#

Súvisiace články

Bol tento článok užitočný?
Backward API a prístupy Zobrazenie interných ID entít Forward