Személyes hozzáférési token (PAT) – mi ez és hogyan használd#

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

A PAT (az angol Personal Access Token, azaz személyes hozzáférési token rövidítése) 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 a jogosultságaidat képviseli – ha átadod valakinek (vagy valamilyen alkalmazásnak), az a te nevedben végezhet műveleteket a Mergadóban, a tokennek engedélyezett hatókörön belül.

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

A PAT a jelszótól eltérően:

  • Korlátozott hatókörrel (scopes) rendelkezik – te döntöd el, mit végezhet el pontosan a token (pl. csak projekteket olvashat, törölni nem tud).
  • Opcionális érvényességi idővel bír – beállíthatod, mikor szűnjön meg a token működése.
  • Bármikor visszavonható jelszóváltoztatás nélkül.
  • Nem módosíthatók vele a fiókbeállítások (jelszó-, e-mail- és számlázási adatok változtatása) – ezekhez hagyományos bejelentkezés szükséges.
  • Nem fedi fel a jelszavadat harmadik fél előtt, akkor sem, ha átadod a tokent.

A PAT a Mergado Editor API eléréséhez készült. Tokennel nem lehet bejelentkezni a Mergado többi szolgáltatásába (Mergado Forum, Mergado Store stb.).

Mikor lesz szükségem PAT-ra?#

Tipikus felhasználási esetek:

  • A Mergado összekapcsolása AI ügynökökkel, például a ChatGPT-vel, Claude-dal vagy Cursorral 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álások – pl. rendszeres adatexport, tömeges projektmódosítások, belső rendszerekkel való integráció.
  • Saját alkalmazások fejlesztése és tesztelése a Mergado API felett.
  • No-code eszközökkel való összekapcsolás, mint például Zapier, Make, n8n vagy Gumloop.

Hogyan generálj PAT-ot?#

  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 egy leíró névvel, amelyről felismered, hol van használva – pl. „Claude Desktop", „Exportáló szkript könyvelőnek". A tokenek kezelésekor a név az elsődleges kapocs, amellyel megkülönböztetheted őket egymástól.

  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 érvényes, amíg manuálisan vissza nem vonod)

    Automatizálásban használt tokenekhez érdemes konkrét érvényességet beállítani (pl. 90 nap) – a rendszeres megújítás csökkenti az esetleges tokenszivárgás következményeit. Fejlesztéshez és teszteléshez elég a rövid érvényesség (7 nap).

  6. Válaszd ki a jogosultságokat (scopes) – lásd Jogosultságok

  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, új tokent 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 egy ún. token-előnézetet látsz mergado_pat_***8046c5 formátumban, ahol az utolsó 6 karakter megegyezik a valódi token végével. Így gyorsan ellenőrizheted, melyik token melyik, anélkül hogy kéznél kellene lennie.

A token érzékeny adat – kezeld úgy, mint egy jelszót. Aki rendelkezik a tokennel, a Mergadóban ugyanolyan jogosultságokkal rendelkezik, mint te az engedélyezett scopes határain belül.

Jogosultságok (scopes)#

A token létrehozásakor jelölőnégyzetekkel választod ki a konkrét jogosultságokat. A jogosultságok logikai csoportokba rendezve jelennek meg (Felhasználó, Webáruház, Projekt), hogy könnyebb legyen eligazodni bennük.

Ajánlás: Csak azokat a jogosultságokat add meg a tokennek, amelyekre az adott alkalmazásnak ténylegesen szüksége van. Ha például egy szkript csak adatokat olvas egy projektből, nincs szüksége írási vagy törlési jogosultságra. Ezt az elvet legkisebb jogosultság elvének (least privilege) hívják.

Felhasználó#

A felhasználói fiókodhoz és az adataidhoz kapcsolódó jogosultságok.

Jogosultság Mit tesz lehetővé
Felhasználói adatok olvasása Hozzáférés a felhasználói adatokhoz – név, felhasználónév, e-mail, regisztrációs dátum stb.
Felhasználó webáruházainak megtekintése A felhasználó által elérhető webáruházak listájának és részleteinek megjelenítése (Tulajdonos, Olvasás vagy Írás jogosultságú webáruházak).
Felhasználói üzenetek olvasása A felhasználói értesítések olvasása – rendszerüzenetek és más alkalmazásoktól érkező üzenetek egyaránt.
Értesítések küldése a felhasználónak Értesítések küldése a felhasználónak (e-mail és frontend értesítés).
A felhasználónál engedélyezett bővítmények olvasása Hozzáférés a felhasználónál bekapcsolt bővítmények listájához.

Webáruház#

Az adott webáruház adataihoz kapcsolódó jogosultságok.

Jogosultság Mit tesz lehetővé
Webáruházi adatok olvasása Hozzáférés a webáruházi adatokhoz – név, domain, exportált tételek száma, hozzáféréssel rendelkező felhasználók stb.
Projektek olvasása a webáruházban Hozzáférés a webáruház összes projektjéhez (exportjához) és azok alapinformációihoz. Nem tartalmaz hozzáférést a szabályokhoz, lekérdezésekhez, elemekhez stb.
A Keychainnel összekapcsolt szolgáltatások adatainak olvasása A Keychain segítségével csatlakoztatott szolgáltatások adatainak olvasása (pl. Heureka, Google Ads…).
A Keychainnel összekapcsolt szolgáltatások adatainak szerkesztése A Keychain segítségével csatlakoztatott szolgáltatások adatainak írása és szerkesztése.
Webáruházi statisztikák olvasása Hozzáférés a webáruházi statisztikákhoz. A statisztikáknak előzetesen össze kell lenniük gyűjtve – a Keychainben megadott adatokat igényli.
Webáruházi statisztikák forrásainak olvasása Hozzáférés a statisztikák forrásainak listájához.
A webáruház Google Analytics adatainak olvasása A webáruház Google Analytics adatainak olvasása. A felhasználónak először a Keychainben kell jogosultságot adnia.
Webáruházi üzenetek olvasása A webáruházi tagoknak küldött értesítések olvasása, beleértve a rendszerüzeneteket is.
Értesítések küldése a webáruháznak Értesítések küldése a webáruházi tagoknak.
A webáruháznál engedélyezett bővítmények olvasása Hozzáférés a webáruháznál bekapcsolt bővítmények listájához.

Projekt#

A webáruházon belüli egyes projektekhez (exportokhoz) kapcsolódó jogosultságok. Ez a csoport a legbővebb – a projekt szabályokat, lekérdezéseket, termékeket, statisztikákat stb. tartalmaz, és minden réteghez külön olvasási és írási jogosultság tartozik.

Jogosultság Mit tesz lehetővé
Projekt adatainak olvasása Hozzáférés a projekt alapinformációihoz – név, feed URL-je, exportált tételek száma stb.
Projekt adatainak szerkesztése A projekt szerkesztése. Nem tartalmaz szabályok, lekérdezések, 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.
Lekérdezések olvasása A projekt lekérdezéseinek olvasása. A lekérdezéseket a felhasználó vagy egy alkalmazás hozza létre.
Lekérdezések szerkesztése Lekérdezések olvasása, törlése és létrehozása. A lekérdezések ezután 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. Lekérdezésekkel való termékszűréshez is elegendő.
Projekt termékeinek szerkesztése 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 a speciális analitikához.
Projekt Google Analytics adatainak olvasása A GA adatok olvasása a projekt kimeneti formátuma szerint szűrve (pl. csak a Heurekáról érkező adatok).
Projekt feldolgozási előzményeinek olvasása A lezajlott feladatok megtekintése – XML importálás, szabályok alkalmazása, XML exportálás (automatikusak is).
Új projektfeldolgozás indítása Feladatok indítása – XML importálás, szabályok alkalmazása, XML exportálás.
Feed auditok olvasása A projekt XML feedjének auditeredményei – talált hibák, hiányzó elemek stb.
Feed audit indítása A projekt XML feedjének új ellenőrzése (auditja) 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 külső felek általi letöltései.
A projektnél engedélyezett bővítmények olvasása Hozzáférés a projektnél bekapcsolt bővítmények listájához.

Fejlesztőknek: az egyes scopes technikai neveit (ID-jét) API formátumban (pl. project.rules.write) az API dokumentáció OAuth scopes oldalán találod.

A tokenek listájában minden sornál látható az engedélyezett jogosultságok száma, és a Megjelenítés gombra kattintva tag formátumban is kibonthatók.

Hogyan használd a tokent?#

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

Authorization: Bearer <a-te-tokened>

API-hívás példa curl segítségével:

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

Az összes végpont 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 alkalmazáshoz/integrációhoz hozz létre külön tokent saját névvel. Így könnyebben visszavonható egy adott integráció anélkül, hogy a többit érintené.
  • A tokennek csak a szükséges jogosultságokat add meg (legkisebb jogosultság elve).
  • Rendszeresen tekintsd át az aktív tokenek listáját, és vonja vissza azokat, amelyeket már nem használsz.
  • Automatizálásban használt tokenekhez állíts be 90 napos érvényességet, és rendszeresen újítsd meg a tokent.

Mit ne tegyél#

  • Ne commitold a tokent a Gitbe és semmilyen más repozitóriumba. Ha ez véletlenül megtörténik, azonnal vonja vissza a tokent – a Git-előzmények nyilvánosan elérhetők a fájl törlése után is.
  • Ne küldd el a tokent e-mailben, Slacken, Teamsen vagy más chat-alkalmazásban sima szövegként.
  • Ne oszd meg egyetlen tokent több személy vagy alkalmazás között.

Mit tegyél kompromittálódás esetén#

Ha arra gyanakszol, hogy a tokened illetéktelen kezekbe került (pl. véletlenül közzétetted egy repozitóriumban, képernyőképen, vagy gyanús aktivitást észlelsz a fiókodon):

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

GYIK#

Elvesztettem a tokent – mi a teendő?#

A tokent többé nem jelenítjük meg. Hozz létre egy újat, és frissítsd az alkalmazásban, ahol volt használva. A régit érdemes visszavonni, 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. Ajánlott azonban minden integrációhoz külön tokent létrehozni – így könnyebben kezelhetők, és szükség esetén egyetlen token visszavonásával lekapcsolható egy adott integráció.

Meddig érvényes a token?#

Addig, ameddig a létrehozáskor beállítottad – 7, 30, 90, 365 nap, vagy Soha. Az aktuális lejárati dátumot a tokenek listájának Lejárat oszlopában látod. Lejárat után a token megszűnik működni, é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, szóközök nélkül másolod-e.
  • Ellenőrizd a fejléc formátumát: Authorization: Bearer <token> (a Bearer szót szóköz követi).
  • A token visszavonásra kerülhetett vagy lejárhatott – a tokenek listájában ellenőrizd a Lejárat oszlopot.
  • Ha a token egyáltalán nem szerepel a listában, törölték – hozz létre újat.

Az API 403 Forbidden hibát ad vissza. Mi a teendő?#

A token érvényes, de nincs jogosultsága az adott műveletre. Ellenőrizd a tokenek listájában a jogosultságait (Jogosultságok oszlop → Megjelenítés), és szükség esetén hozz létre újat bővített scopes-szal. Meglévő tokent nem lehet bővíteni – biztonsági okokból új tokent kell létrehoznod.

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

Nem. A PAT kizárólag a Mergado Editor API-hoz készült. A Mergado többi szolgáltatásába hagyományos Mergado-fiókkal kell bejelentkezni.

Használhatom-e a PAT-ot az ügyfeleim számára nyújtott saját alkalmazásban?#

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

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