OAuth-додатки для партнерів

Матеріал з Planfix

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

Якщо інтеграція потрібна лише одному акаунту, простіше створити додаток акаунту.

Створення додатка

  1. Відкрийте свій партнерський кабінет.
  2. Перейдіть у розділ OAuth-додатки.
  3. Натисніть Створити додаток.
  4. Вкажіть назву та опис, які побачать користувачі та адміністратори.
  5. Виберіть тип OAuth-клієнта.
  6. Додайте Redirect URI.
  7. Виберіть мінімально необхідні scope REST API.
  8. Збережіть додаток і скопіюйте облікові дані.

Після створення додаток є приватним і вимагає явного дозволу в кожному підключуваному акаунті.

Тип OAuth-клієнта

Тип Для яких додатків Облікові дані
Публічний Мобільні, десктопні і браузерні додатки, локальні MCP-клієнти. Тільки client_id. Client secret відсутній; обов'язковий PKCE S256.
Конфіденційний Серверні додатки, де секрет можна зберігати поза пристроєм користувача та клієнтським кодом. client_id і client_secret.

Публічність OAuth-клієнта не пов'язана з публікацією додатка в каталозі. Наприклад, приватний мобільний додаток буде публічним OAuth-клієнтом без секрету.

Redirect URI

Вкажіть усі адреси, на які Planfix може повернути користувача після входу.

  • Для веб-сервісу використовуйте https.
  • http дозволений лише для loopback-адрес, наприклад localhost і 127.0.0.1.
  • Для loopback-адреси клієнт може використовувати динамічний порт; схема, хост, шлях і параметри запиту повинні збігатися.
  • Не використовуйте шаблони, фрагменти URL і Redirect URI, якими ви не керуєте.

Scope

Scope задають максимально можливі повноваження додатка. Запитуйте лише необхідні рівні доступу зі списку scope REST API.

Права додатка не замінюють звичайні права користувача: навіть за наявності scope додаток може працювати лише з доступними користувачу даними.

Зміна Redirect URI або scope створює нову версію дозволів. Раніше підключені акаунти повинні перевірити і дозволити нову версію, а користувачі — виконати підключення знову.

Підключення клієнтського акаунту

Приватний партнерський додаток має бути явно дозволений адміністратором кожного акаунту.

  1. Відкрийте додаток у партнерському кабінеті.
  2. У блоці отримання посилання вкажіть назву клієнтського акаунту.
  3. Скопіюйте сформоване посилання та передайте його адміністратору цього акаунту.
  4. Попросіть адміністратора перевірити власника, Redirect URI і scope, потім дозволити додаток.
  5. Після дозволу користувачі акаунту зможуть проходити OAuth-авторизацію. Кожен користувач окремо підтверджує доступ від свого імені.

Посилання веде в розділ Управління акаунтом → API → Додатки OAuth і MCP і відкриває потрібний додаток.

Адміністратор, який одночасно підключає додаток, може натиснути Дозволити і підключити.

Приватний і опублікований додаток

Статус Як допускається в акаунт
Приватний Завжди вимагає явного дозволу адміністратора кожного акаунту.
Опублікований При політиці Дозволяти опубліковані додатки доступний без окремого дозволу. При політиці Тільки дозволені додатки також вимагає явного дозволу.

Публікація — окрема перевірка Planfix. До подачі додатка підготуйте зрозумілу назву і опис, мінімальний набір scope, робочі Redirect URI та користувацьку документацію з підключення й видалення інтеграції. Уточнити порядок публікації можна в службі підтримки Planfix.

Адреси підключення

Використовуйте глобальні OAuth endpoint того продукту, в якому знаходиться акаунт користувача:



Призначення Адреса
Авторизація https://auth.planfix.com/uk/oauth/authorize
Токен https://auth.planfix.com/uk/oauth/token
Userinfo https://auth.planfix.com/uk/oauth/userinfo
MCP https://mcp.planfix.com/uk/mcp


У глобальний URL не додається назва акаунту. Користувач вибирає акаунт на сторінці Planfix. Повний протокол, параметри resource, PKCE, оновлення і відклик токенів описані в статті OAuth 2.0 для додатків.

Керування додатком

Партнер може:

  • змінити назву та опис;
  • змінити Redirect URI і scope;
  • відключити і знову ввімкнути додаток;
  • замінити client secret конфіденційного додатка;
  • отримати посилання на дозвіл додатка для конкретного акаунту.

Після заміни старий client secret одразу перестає працювати. Оновіть секрет на сервері інтеграції і не передавайте його користувачам.

Вимкнення додатка блокує його OAuth-авторизацію і видані токени у всіх акаунтах. Ця дія зачіпає всіх клієнтів додатка.

Рекомендації перед запуском

  • Використовуйте Authorization Code з PKCE S256 і перевіряйте state.
  • Запитуйте тільки потрібні scope.
  • Показуйте користувачу обраний акаунт після завершення входу.
  • Обробляйте ротацію refresh token: після успішного оновлення старий refresh token більше не діє.
  • Не зберігайте токени, authorization code, code_verifier і client secret у логах.
  • Додайте в свою документацію спосіб вимкнути інтеграцію і видалити користувацькі дані.
  • Перевірте сценарії відкликання дозволу, вимкнення додатка і повторного підключення.

Перейти