Osobní přístupový token (PAT) – co to je a jak ho používat#

Co je osobní přístupový token (PAT)?#

PAT (z anglického Personal Access Token, česky osobní přístupový token) je dlouhý náhodný řetězec, který slouží jako alternativa k heslu pro přístup k Mergado API. Token reprezentuje vás a vaše oprávnění – když ho někomu (nebo nějaké aplikaci) předáte, může za vás v Mergadu provádět akce v rozsahu, který jste tokenu povolili.

Zkratku PAT používáme proto, že je to standardní termín napříč branží (GitHub, GitLab, Atlassian aj.).

PAT na rozdíl od hesla:

• Má omezený rozsah (scopes) – vyberete, co konkrétně smí token dělat (např. jen číst projekty, ne mazat).
• Má volitelnou platnost – můžete nastavit, kdy token přestane fungovat.
• Lze ho kdykoliv zneplatnit bez nutnosti měnit heslo.
• Nelze pomocí něj měnit nastavení účtu (změna hesla, e-mailu, fakturace) – k tomu se musíte přihlásit standardním způsobem.
• Nezpřístupňuje vaše heslo třetí straně, i když token předáte.

PAT je určen pro přístup k Mergado Editor API. Tokenem se nelze přihlašovat do dalších služeb Mergada (Mergado Forum, Mergado Store apod.).

Kdy budu PAT potřebovat?#

Typické scénáře:

• Propojení Mergada s AI agenty typu ChatGPT, Claude nebo Cursor přes Mergado MCP server. Návod najdete v článku Propojení Mergada s AI agenty.
• Vlastní skripty a automatizace – např. pravidelný export dat, hromadné úpravy projektů, integrace do interních systémů.
• Vývoj a testování vlastních aplikací nad Mergado API.
• Propojení s no-code nástroji typu Zapier, Make, n8n nebo Gumloop.

Jak vygenerovat PAT?#

1. Přihlaste se do Mergado Editoru.

2. V pravém horním rohu klikněte na svůj profil → API a přístupy.

3. Klikněte na tlačítko + Vytvořit token.

4. Pojmenujte token popisem, podle kterého poznáte, kde je použitý – např. „Claude Desktop“, „Export skript pro účetní“. Až budete tokeny později spravovat, název je hlavní vodítko, jak je od sebe odlišit.

5. Nastavte platnost tokenu. Volby:

   • 7 dní
   • 30 dní
   • 90 dní
   • 365 dní
   • Nikdy (token bude platit, dokud ho ručně nezneplatníte)

   Pro tokeny v automatizaci doporučujeme nastavit konkrétní platnost (např. 90 dní) – pravidelná obnova snižuje dopad případného úniku tokenu. Pro vývoj a testování stačí krátká platnost (7 dní).

6. Vyberte oprávnění (scopes) – viz Oprávnění

7. Klikněte na Vytvořit.

8. Zkopírujte token a uložte ho na bezpečné místo (správce hesel, šifrovaný soubor). Po opuštění stránky už token znovu nezobrazíme – pokud ho ztratíte, musíte vytvořit nový.

Token má prefix mergado_pat_ následovaný 60 náhodnými znaky, např. mergado_pat_aec7bb21ff4b2c09b156cd3130b4eef0daf69ea2e1e0d62c23472626aa7e72314fdbb53896b2fd8046c5.

Tip: V seznamu tokenů uvidíte tzv. náhled tokenu ve formátu mergado_pat_***8046c5, kde posledních 6 znaků odpovídá koncovce skutečného tokenu. Můžete tak rychle ověřit, který token je který, aniž byste ho museli mít po ruce.

Token je citlivý údaj – chovejte se k němu jako k heslu. Kdokoliv s tokenem má v Mergadu stejná oprávnění jako vy v rozsahu udělených scopes.

Oprávnění (scopes)#

Při tvorbě tokenu vybíráte konkrétní oprávnění zaškrtávacími poli. Oprávnění jsou seskupena do logických celků (Uživatel, E-shop, Projekt), abyste se v nich snáze zorientovali.

Doporučení: Udělte tokenu jen ta oprávnění, která daná aplikace skutečně potřebuje. Pokud například skript jen čte data z projektu, nepotřebuje práva na zápis ani mazání. Tomuto principu se říká princip nejmenších oprávnění (least privilege).

Uživatel#

Oprávnění týkající se vašeho uživatelského účtu a informací o vás.

E-shop#

Oprávnění k datům konkrétního e-shopu.

Projekt#

Oprávnění k jednotlivým projektům (exportům) v rámci e-shopu. Tato skupina je nejrozsáhlejší – projekt obsahuje pravidla, výběry, produkty, statistiky atd. a každá z těchto vrstev má vlastní oprávnění pro čtení a zápis.

Pro vývojáře: technické názvy (ID) jednotlivých scopes v API formátu (např. project.rules.write) najdete v API dokumentaci OAuth scopes.

V seznamu tokenů u každého řádku vidíte počet udělených oprávnění a kliknutím na Zobrazit je můžete rozbalit jako tagy.

Jak token použít?#

Token se posílá v hlavičce HTTP požadavku jako Bearer token:

Authorization: Bearer <váš-token>

Příklad volání API přes curl:

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

Kompletní popis všech endpointů najdete v API dokumentaci:

• API reference: api-docs.mergado.com
• Postup autorizace: mergado.github.io/docs/api/authorization.html

Bezpečnost a správa tokenů#

Co dělat#

• Token uložte do správce hesel nebo do šifrované konfigurace (např. proměnná prostředí, secret manager).
• Pro každou aplikaci/integraci vytvořte samostatný token s vlastním názvem. Snáze se pak zneplatní konkrétní integrace bez dopadu na ostatní.
• Tokenu udělte jen ta oprávnění, která potřebuje (princip nejmenších oprávnění).
• Pravidelně procházejte seznam aktivních tokenů a zneplatňujte ty, které už nepoužíváte.
• Pro tokeny v automatizaci nastavte platnost 90 dní a token periodicky obnovujte.

Co nedělat#

• Necommitujte token do Gitu ani do žádného repozitáře. Pokud k tomu omylem dojde, token okamžitě zneplatněte – historie Gitu je veřejně přístupná i po smazání souboru.
• Neposílejte token přes e-mail, Slack, Teams ani jiné chat aplikace v plain textu.
• Nesdílejte jeden token mezi více lidmi nebo aplikacemi.

Co dělat při kompromitaci#

Pokud máte podezření, že se vám token dostal do nepovolaných rukou (např. omylem zveřejněný v repozitáři, screenshotu, podezřelá aktivita na účtu):

1. Okamžitě jděte do API a přístupy a token zneplatněte (ikona koše v seznamu).
2. Vytvořte nový token a aktualizujte ho ve všech integracích, kde byl použit.

FAQ#

Ztratil jsem token, co teď?#

Token už znovu nezobrazíme. Vytvořte nový a aktualizujte ho v aplikaci, kde byl použit. Starý token doporučujeme zneplatnit, ať se nedá zneužít, pokud ho někdo později najde.

Kolik tokenů můžu mít?#

Počet osobních přístupových tokenů na jednoho uživatele není aktuálně omezen. Doporučujeme ale vytvářet samostatný token pro každou integraci – snadněji se pak spravují a v případě potřeby lze konkrétní integraci odpojit zneplatněním jediného tokenu.

Jak dlouho je token platný?#

Tak dlouho, jak jste si nastavili při jeho vytvoření – 7, 30, 90, 365 dní, nebo Nikdy. Aktuální datum vypršení vidíte v seznamu tokenů ve sloupci Vyprší. Po vypršení token přestane fungovat a musíte si vytvořit nový.

API mi vrací 401 Unauthorized. Co s tím?#

• Zkontrolujte, že token kopírujete celý a bez mezer na začátku/konci.
• Zkontrolujte formát hlavičky: Authorization: Bearer <token> (slovo Bearer se odděluje mezerou).
• Token mohl být zneplatněn nebo expiroval – v seznamu tokenů zkontrolujte sloupec Vyprší.
• Pokud token chybí v seznamu úplně, byl smazán – vytvořte nový.

API mi vrací 403 Forbidden. Co s tím?#

Token je platný, ale nemá oprávnění na danou akci. Zkontrolujte v seznamu tokenů jeho oprávnění (sloupec Oprávnění → Zobrazit) a v případě potřeby vytvořte nový s rozšířenými scopes. Existující token rozšířit nelze – z bezpečnostních důvodů musíte vytvořit nový.

Můžu token použít k přihlášení do Mergado Fóra nebo Mergado Store?#

Ne. PAT je určen výhradně pro Mergado Editor API. Pro ostatní služby Mergada se přihlašujte standardně přes Mergado účet.

Můžu PAT používat ve své aplikaci, kterou poskytuju klientům?#

Ne. PAT reprezentuje konkrétního uživatele. Pokud vyvíjíte aplikaci, kterou budou používat zákazníci Mergada, použijte OAuth flow – každý uživatel se autorizuje sám pod svým účtem. Více v API dokumentaci.

Související odkazy#

• API a přístupy – správa osobních přístupových tokenů
• Propojení Mergada s AI agenty (ChatGPT, Claude, Cursor)
• API reference: api-docs.mergado.com
• Postup autorizace: mergado.github.io/docs/api/authorization.html