Személyes hozzáférési token (PAT)#

Mi a személyes hozzáférési token (PAT)?#

A PAT (Personal Access Token, személyes hozzáférési token) egy hosszú, véletlenszerű karakterlánc, amely jelszóalternatívaként szolgál a Mergado API eléréséhez. A token téged és az engedélyeidet képviseli – ha átadod egy alkalmazásnak, az a te nevedben tud műveleteket végezni a Mergadóban, az általad engedélyezett hatókörön belül.

A PAT rövidítést azért használjuk, mert ez az iparág szabványos szakkifejezése (GitHub, GitLab, Atlassian stb.).

A PAT a jelszóval szemben:

  • Korlátozott hatókörrel (scope-okkal) rendelkezik – te döntöd el, mit tehet pontosan a token (pl. csak projekteket olvashat, nem törölhet).
  • Választható érvényességgel bír – beállíthatod, mikor szűnjön meg működni.
  • Bármikor érvényteleníthető jelszócsere nélkül.
  • Nem lehet vele megváltoztatni a fiókbeállításokat (jelszó, e-mail, számlázás) – ehhez a szokásos módon kell bejelentkezni.
  • Nem teszi hozzáférhetővé a jelszavadat harmadik fél számára, még ha a tokent át is adod.

A PAT a Mergado Editor API eléréséhez való. A tokennel nem lehet bejelentkezni a Mergado többi szolgáltatásába (Mergado Forum, Mergado Store stb.).

Mikor van szükség PAT-ra?#

Tipikus esetek:

  • A Mergado összekapcsolása AI ügynökökkel – pl. ChatGPT, Claude vagy Cursor a Mergado MCP szerveren keresztül. Az útmutatót a Mergado összekapcsolása AI ügynökökkel cikkben találod.
  • Saját szkriptek és automatizáció – pl. rendszeres adatexport, tömeges projektmódosítások, belső rendszerekbe való integráció.
  • Saját alkalmazások fejlesztése és tesztelése a Mergado API felett.
  • Összekapcsolás no-code eszközökkel – pl. Zapier, Make, n8n vagy Gumloop.

PAT létrehozása#

  1. Jelentkezz be a Mergado Editorba.

  2. A jobb felső sarokban kattints a profilodra → API és hozzáférések.

  3. Kattints a + Token létrehozása gombra.

  4. Nevezd el a tokent leíró névvel, amelyből tudni fogod, hol használod – pl. „Claude Desktop", „Könyvelői exportszkript". A név az elsődleges útmutatód a tokenek megkülönböztetéséhez.

  5. Állítsd be a token érvényességét. Lehetőségek:

    • 7 nap
    • 30 nap
    • 90 nap
    • 365 nap
    • Soha (a token addig marad érvényes, amíg kézzel érvényteleníted)

    Automatizáláshoz javasolt konkrét érvényességet beállítani (pl. 90 nap) – a rendszeres megújítás csökkenti az esetleges tokenszivárgás hatását. Fejlesztéshez és teszteléshez elég a rövid érvényesség (7 nap).

  6. Válaszd ki az engedélyeket (scope-okat) – lásd Engedélyek.

  7. Kattints a Létrehozás gombra.

  8. Másold ki a tokent és mentsd el biztonságos helyre (jelszókezelő, titkosított fájl). Az oldal elhagyása után a tokent többé nem jelenítjük meg – ha elveszíted, újat kell létrehoznod.

A token előtagja mergado_pat_, amelyet 60 véletlenszerű karakter követ, pl. mergado_pat_aec7bb21ff4b2c09b156cd3130b4eef0daf69ea2e1e0d62c23472626aa7e72314fdbb53896b2fd8046c5.

Tipp: A tokenek listájában látni fogod az ún. tokenelőnézetet mergado_pat_***8046c5 formátumban, ahol az utolsó 6 karakter megfelel a tényleges token végének. Így gyorsan ellenőrizheted, melyik token melyik.

A token érzékeny adat – kezeld ugyanúgy, mint a jelszavadat. Bárki, aki rendelkezik a tokennel, ugyanolyan engedélyekkel bír a Mergadóban, mint te, az engedélyezett scope-ok keretein belül.

Engedélyek (scope-ok)#

A token létrehozásakor jelölőnégyzetekkel választod ki az engedélyeket. Ezek logikai csoportokba vannak rendezve (Felhasználó, Webáruház, Projekt), hogy könnyebb legyen eligazodni bennük.

Javaslat: Csak azokat az engedélyeket add meg a tokennek, amelyekre az adott alkalmazásnak valóban szüksége van. Ha egy szkript csak projektadatokat olvas, nincs szüksége írási vagy törlési jogokra. Ezt az elvet minimális jogosultság elvének (least privilege) nevezzük.

Felhasználó#

A felhasználói fiókodra vonatkozó engedélyek.

Engedély Mit tesz lehetővé
Felhasználói adatok olvasása Hozzáférés a felhasználói információkhoz – név, felhasználónév, e-mail, regisztráció dátuma stb.
Felhasználó webáruházainak olvasása Azon webáruházak listájának és részleteinek megjelenítése, amelyekhez a felhasználónak hozzáférése van (Tulajdonos, Olvasás vagy Írás jogkörrel).
Felhasználó üzeneteinek olvasása A felhasználó értesítéseinek olvasása – rendszerüzenetek és más bővítményektől érkező üzenetek.
Üzenetek küldése a felhasználónak Értesítések küldése a felhasználónak (e-mail és frontend értesítések).
Felhasználónál engedélyezett bővítmények olvasása Hozzáférés a felhasználónál engedélyezett bővítmények listájához.

Webáruház#

Egy adott webáruház adataira vonatkozó engedélyek.

Engedély Mit tesz lehetővé
Webáruház adatainak olvasása Hozzáférés a webáruház információihoz – név, domain, exportált termékek száma, hozzáféréssel rendelkező felhasználók stb.
Webáruházban lévő projektek olvasása Hozzáférés a webáruház összes projektjéhez (exportjához) és azok alapvető adataihoz. Nem tartalmaz hozzáférést szabályokhoz, kiválasztásokhoz, elemekhez stb.
Keychain-en keresztül csatlakoztatott szolgáltatások adatainak olvasása Keychain-en keresztül csatlakoztatott szolgáltatások (pl. Heureka, Google Ads…) adatainak olvasása.
Keychain-en keresztül csatlakoztatott szolgáltatások adatainak szerkesztése Keychain-en keresztül csatlakoztatott szolgáltatások adatainak írása és szerkesztése.
Webáruház statisztikáinak olvasása Hozzáférés a webáruház statisztikáihoz. A statisztikákat előzetesen össze kell gyűjteni – a Keychain-ben megadott adatokat igényli.
Webáruház statisztikai forrásainak olvasása Hozzáférés azon források listájához, amelyekből a statisztikák gyűjtése történik.
Webáruház Google Analytics adatainak olvasása A webáruház Google Analytics adatainak olvasása. A felhasználónak először engedélyt kell adnia a Keychain-en keresztül.
Webáruház üzeneteinek olvasása A webáruház tagjainak küldött értesítések olvasása, beleértve a rendszerüzeneteket.
Üzenetek küldése a webáruháznak Értesítések küldése a webáruház tagjainak.
Webáruháznál engedélyezett bővítmények olvasása Hozzáférés a webáruháznál engedélyezett bővítmények listájához.

Projekt#

A webáruházon belüli egyes projektekre (exportokra) vonatkozó engedélyek. Ez a csoport a legterjedelmesebb – a projekt tartalmaz szabályokat, kiválasztásokat, termékeket, statisztikákat stb., és ezek mindegyike saját olvasási és írási engedélyekkel rendelkezik.

Engedély Mit tesz lehetővé
Projektadatok olvasása Hozzáférés a projekt alapvető adataihoz – név, feed URL, exportált termékek száma stb.
Projektadatok szerkesztése A projekt szerkesztése. Nem tartalmazza szabályok, kiválasztások, elemek stb. létrehozását.
Elemek olvasása A projekt elemeinek megjelenítése – név, láthatóság és egyéb tulajdonságok.
Elemek szerkesztése Elemek létrehozása, szerkesztése és törlése a projektben.
Kiválasztások olvasása Kiválasztások (queries) olvasása a projektben. A kiválasztásokat felhasználó vagy alkalmazás hozza létre.
Kiválasztások szerkesztése Kiválasztások olvasása, törlése és létrehozása. A kiválasztások termékek szűrésére használhatók.
Szabályok olvasása A projekt összes szabályának megjelenítése.
Szabályok szerkesztése Szabályok törlése, szerkesztése és létrehozása a projektben.
Változók olvasása A projekt változóinak megjelenítése – név, típus és egyéb adatok.
Változók szerkesztése Változók törlése, szerkesztése és létrehozása a projektben.
Projekt termékeinek olvasása A projekt termékeinek megjelenítése. Elegendő a termékek kiválasztásokkal történő szűréséhez is.
Projekt termékeibe való írás Termékek törlése, szerkesztése és létrehozása a projektben.
Projekt statisztikáinak olvasása Hozzáférés a projekt statisztikáihoz és haladó analitikájához.
Projekt Google Analytics adatainak olvasása A GA adatainak olvasása a projekt kimeneti formátuma szerint szűrve (pl. csak a Heureka adatai).
Projekt feldolgozási előzményeinek olvasása Elvégzett feladatok megjelenítése – XML-importálás, szabályok alkalmazása, XML-exportálás (automatikusak is).
Új projektfeldolgozások indítása Feladatok indítása – XML-importálás, szabályok alkalmazása, XML-exportálás.
Feed-auditek olvasása A projekt XML-feedjének auditeredményei – talált problémák, hiányzó elemek stb.
Feed-auditek indítása A projekt XML-feedjének új validálásának (auditjának) indítása.
Projekt előzményeinek olvasása Hozzáférés a projekt naplóihoz – elvégzett feladatok és a kimeneti XML-feed harmadik felek általi letöltései.
Projektnél engedélyezett bővítmények olvasása Hozzáférés a projektnél engedélyezett bővítmények listájához.

Fejlesztőknek: az egyes scope-ok API-formátumú technikai neveit (pl. project.rules.write) az API dokumentáció OAuth scope-ok oldalán találod.

A tokenek listájában minden sornál látod az engedélyezett jogosultságok számát, és a Megjelenítés gombra kattintva kibővítheted azokat tagek formájában.

A token használata#

A tokent Bearer tokenként az HTTP-kérés fejlécében kell elküldeni:

Authorization: Bearer <a-te-tokened>

Példa API-hívásra curl segítségével:

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

Az összes endpoint teljes leírását az API-dokumentációban találod:

Biztonság és tokenkezelés#

Mit tegyél#

  • A tokent mentsd el jelszókezelőbe vagy titkosított konfigurációba (pl. környezeti változó, secret manager).
  • Minden integrációhoz hozz létre külön tokent saját névvel. Így könnyebb egy konkrét integráció érvénytelenítése a többire való hatás nélkül.
  • A tokennek csak azokat az engedélyeket add meg, amelyekre szüksége van (minimális jogosultság elve).
  • Rendszeresen nézd át az aktív tokenek listáját, és érvénytelenítsd azokat, amelyeket már nem használsz.
  • Az automatizálásban használt tokenekhez állíts be 90 napos érvényességet, és rendszeresen újítsd meg.

Mit ne tegyél#

  • Ne commitold a tokent Gitbe és semmilyen repository-ba. Ha ez véletlenül megtörténik, azonnal érvénytelenítsd a tokent – a Git előzménye publikusan hozzáférhető a fájl törlése után is.
  • Ne küldd el a tokent e-mailben, Slacken, Teamsen vagy más csevegőprogramban egyszerű szövegként.
  • Ne ossz meg egy tokent több ember vagy alkalmazás között.

Mi a teendő kompromittálódás esetén#

Ha gyanítod, hogy a token illetéktelen kezekbe került (pl. véletlenül közzétéve egy repository-ban, képernyőképen, vagy gyanús fiókaktivitás esetén):

  1. Azonnal menj az API és hozzáférések oldalra, és érvénytelenítsd a tokent (kuka ikon a listában).
  2. Hozz létre új tokent, és frissítsd minden integrációban, ahol használva volt.

GYIK#

Elveszítettem a tokent – mi a teendő?#

A tokent többé nem jelenítjük meg. Hozz létre újat, és frissítsd az alkalmazásban, ahol használva volt. A régi tokent érdemes érvényteleníteni, hogy ne lehessen visszaélni vele, ha valaki később megtalálja.

Hány tokenem lehet?#

A személyes hozzáférési tokenek száma felhasználónként jelenleg nincs korlátozva. Azt javasoljuk azonban, hogy minden integrációhoz hozz létre külön tokent – így könnyebben kezelhető, és szükség esetén egyetlen token érvénytelenítésével lekapcsolható egy konkrét integráció.

Meddig érvényes a token?#

Addig, amíg a létrehozásakor beállítottad – 7, 30, 90, 365 napig, vagy Soha. A lejárati dátumot a tokenek listájában a Lejár oszlopban látod. A lejárat után a token leáll, és újat kell létrehoznod.

Az API 401 Unauthorized hibát ad vissza – mi a teendő?#

  • Ellenőrizd, hogy a tokent teljes egészében másolod ki, szóközök nélkül az elején/végén.
  • Ellenőrizd a fejléc formátumát: Authorization: Bearer <token> (a Bearer szót szóköz választja el a tokentől).
  • A token érvénytelenítve lehetett vagy lejárt – ellenőrizd a Lejár oszlopot a tokenek listájában.
  • Ha a token egyáltalán nem szerepel a listában, törölve lett – hozz létre újat.

Az API 403 Forbidden hibát ad vissza – mi a teendő?#

A token érvényes, de nincs engedélye az adott művelethez. Ellenőrizd a tokenek listájában az engedélyeit (Engedélyek oszlop → Megjelenítés), és szükség esetén hozz létre újat bővített scope-okkal. A meglévő tokent nem lehet utólag bővíteni – biztonsági okokból újat kell létrehoznod.

Használhatom a tokent a Mergado Fórumba vagy Mergado Store-ba való bejelentkezéshez?#

Nem. A PAT kizárólag a Mergado Editor API-hoz való. A Mergado többi szolgáltatásához a szokásos Mergado-fiókkal jelentkezz be.

Használhatom a PAT-et a saját, ügyfeleknek nyújtott alkalmazásomban?#

Nem. A PAT egy konkrét felhasználót képvisel. Ha olyan alkalmazást fejlesztesz, amelyet Mergado-ügyfelek fognak használni, használj OAuth flow-t – minden felhasználó a saját fiókja alatt autorizál. Bővebb információ az API dokumentációban.

Kapcsolódó hivatkozások#

Kapcsolódó cikkek

Hasznos volt ez a cikk?
Backward API és hozzáférések Integrációk és automatizálás Forward