Персональний токен доступу (PAT) – що це таке і як ним користуватися#

Що таке персональний токен доступу (PAT)?#

PAT (від англійського Personal Access Token, українською — персональний токен доступу) — це довгий випадковий рядок, який слугує альтернативою паролю для доступу до Mergado API. Токен представляє вас і ваші права доступу – коли ви передасте його комусь (або якомусь застосунку), той зможе виконувати дії в Mergado від вашого імені в обсязі, який ви дозволили токену.

Скорочення PAT ми використовуємо тому, що це стандартний термін у всій галузі (GitHub, GitLab, Атлассіан тощо).

На відміну від пароля PAT:

  • Має обмежений обсяг (scopes) – ви вибираєте, що саме може робити токен (наприклад, лише читати проєкти, але не видаляти).
  • Має необов’язковий строк дії – можете встановити, коли токен перестане працювати.
  • Його можна будь-коли анулювати без потреби змінювати пароль.
  • З його допомогою не можна змінювати налаштування облікового запису (зміна пароля, електронної адреси, виставлення рахунків) – для цього потрібно увійти стандартним способом.
  • Не розкриває ваш пароль третій стороні, навіть якщо ви передасте токен.

PAT призначений для доступу до Mergado Editor API. За допомогою токена не можна входити в інші сервіси Mergado (Mergado Forum, Mergado Store тощо).

Коли мені знадобиться PAT?#

Типові сценарії:

  • Підключення Mergado до ШІ-агентів на кшталт ChatGPT, Claude або Cursor через Mergado MCP-сервер. Інструкцію знайдете у статті Підключення Mergado до ШІ-агентів.
  • Власні скрипти та автоматизація – наприклад, регулярний експорт даних, масові зміни проєктів, інтеграція у внутрішні системи.
  • Розробка і тестування власних застосунків на основі Mergado API.
  • Підключення до no-code інструментів на кшталт Zapier, Make, n8n або Gumloop.

Як згенерувати PAT?#

  1. Увійдіть у Mergado Editor.

  2. У правому верхньому куті клацніть на свій профіль → API and Access.

  3. Натисніть кнопку + Create token.

  4. Назвіть токен так, щоб за назвою було зрозуміло, де його використано, – наприклад, «Claude Desktop», «Скрипт експорту для бухгалтера». Коли пізніше керуватимете токенами, назва буде головною підказкою, як їх розрізнити.

  5. Установіть строк дії токена. Варіанти:

    • 7 days
    • 30 days
    • 90 days
    • 365 days
    • Never (токен буде чинним, доки ви вручну його не анулюєте)

    Для токенів в автоматизації рекомендуємо встановити конкретний строк дії (наприклад, 90 днів) – регулярне оновлення зменшує наслідки можливого витоку токена. Для розробки і тестування достатньо короткого строку дії (7 днів).

  6. Виберіть права доступу (scopes) – див. Права доступу

  7. Натисніть Create.

  8. Скопіюйте токен і збережіть його в надійному місці (менеджер паролів, зашифрований файл). Після виходу зі сторінки ми вже не покажемо токен повторно – якщо ви його втратите, доведеться створити новий.

Токен має префікс mergado_pat_, за яким іде 60 випадкових символів, наприклад mergado_pat_aec7bb21ff4b2c09b156cd3130b4eef0daf69ea2e1e0d62c23472626aa7e72314fdbb53896b2fd8046c5.

Порада: У списку токенів ви побачите так званий попередній перегляд токена у форматі mergado_pat_***8046c5, де останні 6 символів відповідають закінченню справжнього токена. Так можна швидко перевірити, який токен який, не маючи його під рукою.

Токен — це конфіденційні дані, поводьтеся з ним як із паролем. Будь-хто, хто має токен, має в Mergado ті самі права доступу, що й ви, в обсязі наданих scopes.

Права доступу (scopes)#

Під час створення токена ви вибираєте конкретні права доступу за допомогою прапорців. Права доступу згруповано в логічні блоки (User, E-shop, Project), щоб вам було легше в них зорієнтуватися.

Рекомендація: Надайте токену лише ті права доступу, які справді потрібні відповідному застосунку. Якщо, наприклад, скрипт лише читає дані з проєкту, йому не потрібні права на запис чи видалення. Цей принцип називається принципом найменших привілеїв (least privilege).

User #

Права доступу, що стосуються вашого облікового запису користувача та інформації про вас.

Право доступу Що дозволяє
Read user data Доступ до інформації про користувача – ім’я, ім’я користувача, електронна адреса, дата реєстрації тощо.
Read user’s e-shops Перегляд списку інтернет-магазинів, до яких користувач має доступ (як Owner, Read або Write), і їхніх подробиць.
Read user notifications Читання сповіщень користувача – системних повідомлень і повідомлень від інших застосунків.
Send notifications to user Надсилання сповіщень користувачу (електронною поштою і в інтерфейсі).
Read user’s enabled extensions Доступ до списку ввімкнених розширень користувача.

E-shop #

Права доступу до даних конкретного інтернет-магазину.

Право доступу Що дозволяє
Read e-shop data Доступ до інформації про інтернет-магазин – назва, домен, кількість експортованих позицій, користувачі з доступом тощо.
Read e-shop’s projects Доступ до всіх проєктів (експортів) інтернет-магазину та їхньої основної інформації. Не охоплює доступ до правил, вибірок, елементів тощо.
Read data of services connected via Keychain Читання даних із сервісів, підключених через Keychain (наприклад, Heureka, Google Ads…).
Edit data in services connected via Keychain Запис і зміна даних у сервісах, підключених через Keychain.
Read e-shop statistics Доступ до статистики інтернет-магазину. Статистику потрібно заздалегідь зібрати – для цього необхідно заповнити дані в Keychain.
Read e-shop statistics sources Доступ до списку джерел, з яких збирається статистика.
Read e-shop Google Analytics Читання даних із Google Analytics інтернет-магазину. Користувач спершу має надати дозвіл через Keychain.
Read e-shop notifications Читання сповіщень, надісланих учасникам інтернет-магазину, зокрема системних повідомлень.
Send notifications to e-shop Надсилання сповіщень учасникам інтернет-магазину.
Read e-shop’s enabled extensions Доступ до списку ввімкнених розширень інтернет-магазину.

Project #

Права доступу до окремих проєктів (експортів) у межах інтернет-магазину. Ця група найбільша – проєкт містить правила, вибірки, товари, статистику тощо, і кожен із цих шарів має власні права доступу для читання і запису.

Право доступу Що дозволяє
Read project data Доступ до основної інформації про проєкт – назва, URL фіду, кількість експортованих позицій тощо.
Edit project data Зміна проєкту. Не охоплює створення правил, вибірок, елементів тощо.
Read elements Перегляд елементів проєкту – назва, видимість та інші властивості.
Edit elements Створення, зміна і видалення елементів у проєкті.
Read queries Читання вибірок (queries) у проєкті. Вибірки створює користувач або застосунок.
Edit queries Читання, видалення і створення вибірок. Вибірки потім можна використовувати для фільтрування товарів.
Read rules Перегляд усіх правил у проєкті.
Edit rules Видалення, зміна і створення нових правил у проєкті.
Read variables Перегляд змінних проєкту – назва, тип та інша інформація.
Edit variables Видалення, зміна і створення змінних у проєкті.
Read project products Перегляд товарів проєкту. Достатньо і для фільтрування товарів за допомогою вибірок.
Write to project products Видалення, зміна і створення товарів у проєкті.
Read project statistics Доступ до статистики проєкту і розширеної аналітики.
Read project Google Analytics Читання даних із GA, відфільтрованих за вихідним форматом проєкту (наприклад, лише дані з Heureka).
Read project processing history Перегляд виконаних завдань – імпорт з XML, застосування правил, експорт у XML (зокрема автоматичних).
Trigger new project processing Запуск завдань – імпорт з XML, застосування правил, експорт у XML.
Read feed audits Читання результатів аудиту XML-фіду проєкту – знайдені проблеми, відсутні елементи тощо.
Trigger feed audits Запуск нової валідації (аудиту) XML-фіду проєкту.
Read project history Доступ до журналів проєкту – виконані завдання і завантаження вихідного XML-фіду третіми сторонами.
Read project’s enabled extensions Доступ до списку ввімкнених розширень проєкту.

Для розробників: технічні назви (ID) окремих scopes у форматі API (наприклад, project.rules.write) знайдете в документації API щодо OAuth scopes.

У списку токенів біля кожного рядка ви бачите кількість наданих прав доступу, а натиснувши Show, можете розгорнути їх як теги.

Як використовувати токен?#

Токен надсилається в заголовку HTTP-запиту як Bearer-токен:

Authorization: Bearer <ваш-токен>

Приклад виклику API через curl:

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

Повний опис усіх ендпоінтів знайдете в документації API:

Безпека і керування токенами#

Що робити#

  • Зберігайте токен у менеджері паролів або в зашифрованій конфігурації (наприклад, змінна середовища, менеджер секретів).
  • Для кожного застосунку/інтеграції створіть окремий токен із власною назвою. Тоді легше анулювати конкретну інтеграцію, не зачіпаючи інші.
  • Надайте токену лише ті права доступу, які йому потрібні (принцип найменших привілеїв).
  • Регулярно переглядайте список активних токенів і анулюйте ті, якими вже не користуєтеся.
  • Для токенів в автоматизації встановіть строк дії 90 днів і періодично оновлюйте токен.

Чого не робити#

  • Не комітьте токен у Git чи будь-який інший репозиторій. Якщо це станеться помилково, негайно анулюйте токен – історія Git залишається загальнодоступною і після видалення файлу.
  • Не надсилайте токен електронною поштою, у Slack, Teams чи інших чат-застосунках у вигляді звичайного тексту.
  • Не діліться одним токеном між кількома людьми або застосунками.

Що робити в разі компрометації#

Якщо ви підозрюєте, що токен потрапив до сторонніх рук (наприклад, його випадково опубліковано в репозиторії, на знімку екрана, або в обліковому записі помічено підозрілу активність):

  1. Негайно перейдіть до API and Access і анулюйте токен (піктограма кошика в списку).
  2. Створіть новий токен і оновіть його в усіх інтеграціях, де його використовували.

Часті запитання#

Я втратив токен, що тепер?#

Токен ми вже не покажемо повторно. Створіть новий і оновіть його в застосунку, де його використовували. Старий токен рекомендуємо анулювати, щоб ним не можна було зловживати, якщо хтось його пізніше знайде.

Скільки токенів я можу мати?#

Кількість персональних токенів доступу на одного користувача наразі не обмежена. Проте рекомендуємо створювати окремий токен для кожної інтеграції – так ними легше керувати, а за потреби можна від’єднати конкретну інтеграцію, анулювавши лише один токен.

Як довго токен чинний?#

Стільки, скільки ви встановили під час його створення, – 7, 30, 90, 365 днів або Never. Поточну дату закінчення строку дії бачите в списку токенів у стовпці Expires. Після закінчення строку дії токен перестане працювати, і вам доведеться створити новий.

API повертає мені 401 Unauthorized. Що робити?#

  • Перевірте, що копіюєте токен повністю і без пробілів на початку/в кінці.
  • Перевірте формат заголовка: Authorization: Bearer <token> (слово Bearer відокремлюється пробілом).
  • Токен міг бути анульований або строк його дії закінчився – у списку токенів перевірте стовпець Expires.
  • Якщо токена в списку взагалі немає, його було видалено – створіть новий.

API повертає мені 403 Forbidden. Що робити?#

Токен чинний, але не має права доступу для виконання цієї дії. Перевірте в списку токенів його права доступу (стовпець Permissions → Show) і за потреби створіть новий із розширеними scopes. Розширити наявний токен не можна – з міркувань безпеки потрібно створити новий.

Чи можу я використати токен для входу в Mergado Forum або Mergado Store?#

Ні. PAT призначений виключно для Mergado Editor API. До інших сервісів Mergado входьте стандартно через обліковий запис Mergado.

Чи можу я використовувати PAT у своєму застосунку, який надаю клієнтам?#

Ні. PAT представляє конкретного користувача. Якщо ви розробляєте застосунок, яким користуватимуться клієнти Mergado, використовуйте процес авторизації OAuth – кожен користувач авторизується сам під своїм обліковим записом. Докладніше в документації API.

Пов’язані посилання#

Пов’язані статті

Чи була ця стаття корисною?