OAuth 2.0 для додатків

OAuth 2.0 дає змогу застосунку отримувати доступ до Planfix від імені користувача, не запитуючи та не зберігаючи пароль користувача.

Planfix використовує потік Authorization Code з обов’язковим PKCE S256. OAuth можна використовувати для підключення до REST API або до сервера MCP Planfix.

Якщо ви хочете підключити готовий AI-клієнт, почніть із MCP. Якщо ви керуєте доступом у своєму акаунті, див. Додатки OAuth і MCP в акаунті. Партнерам і розробникам інтеграцій для кількох акаунтів слід переглянути OAuth-додатки для партнерів.

Варіанти реєстрації застосунку

Варіант	Коли використовувати	Де працює
Застосунок, що належить акаунту	Інтеграція призначена для одного акаунта, і клієнту потрібен заздалегідь визначений client_id.	Лише в акаунті, якому він належить.
Застосунок, що належить партнеру	Один і той самий застосунок має підключатися до кількох акаунтів клієнтів.	В акаунтах, у яких це дозволено політикою безпеки або адміністратором.
Автоматична реєстрація клієнта MCP	Клієнт MCP підтримує документ метаданих Client ID (CIMD) або динамічну реєстрацію клієнта (DCR).	Сама реєстрація не надає доступу до акаунта. Застосунок усе одно має бути дозволений у вибраному акаунті.

CIMD і DCR доступні лише для підключень MCP. Для REST API використовуйте застосунок, що належить акаунту або партнеру.

Кінцеві точки OAuth

Для нових інтеграцій слід використовувати глобальні кінцеві точки. Назва акаунта не входить до цих URL-адрес: користувач вибирає акаунт під час авторизації.

Призначення	Адреса
Емітент	https://auth.planfix.com
Авторизація	https://auth.planfix.com/oauth/authorize
Токен	https://auth.planfix.com/oauth/token
Інформація про користувача	https://auth.planfix.com/oauth/userinfo
Відкликання токена	https://auth.planfix.com/oauth/revoke
Динамічна реєстрація клієнта MCP	https://auth.planfix.com/oauth/register

Метадані сервера авторизації доступні за стандартними кінцевими точками:

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

URI перенаправлення

URI перенаправлення потрібно зареєструвати в налаштуваннях застосунку. Значення, надіслане в запиті авторизації, має збігатися із зареєстрованим URI.

Дозволено використовувати:

• URL-адреси з протоколом https;
• URL-адреси з протоколом http лише для хостів loopback, наприклад localhost або 127.0.0.1.

Для URI loopback порт може бути динамічним, але схема, хост, шлях і запит мають збігатися. Фрагменти URL-адрес і дані користувача в URL-адресі не допускаються.

Рівні доступу

Застосунок отримує лише ті рівні доступу, або scopes, які були дозволені заздалегідь. Повний список див. у розділі Рівні доступу REST API.

Запитуваний набір має бути підмножиною областей доступу, зареєстрованих для застосунку. Області доступу застосунку не розширюють дозволи користувача в Planfix: застосунок може отримувати доступ лише до даних, доступних співробітнику, який його підключив.

Керовані застосунки також отримують службові області доступу userinfo, openid і email.

Авторизація користувача

Згенеруйте code_verifier і його представлення SHA-256 — code_challenge, а потім відкрийте кінцеву точку авторизації в браузері.

Приклад для REST API:

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

Для MCP додайте параметр resource із точною URL-адресою сервера MCP:

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp

Параметр	Опис
client_id	Ідентифікатор зареєстрованого застосунку. Для CIMD це URL-адреса документа метаданих клієнта.
redirect_uri	Один із дозволених URI перенаправлення.
response_type	Має бути code.
scope	Необхідні дозволи, розділені пробілами. Цей параметр обов’язковий для REST API. Клієнт MCP може його не вказувати — у такому разі використовуються області доступу, дозволені для застосунку.
state	Випадкове значення, яке захищає запит від підміни. Після перенаправлення застосунок має перевірити його.
code_challenge	Хеш SHA-256 від code_verifier у форматі Base64url без заповнення.
code_challenge_method	Підтримується лише S256.
resource	Для MCP — точна URL-адреса https://mcp.planfix.com/mcp. Не надсилайте цей параметр для REST API.

Користувач вибирає акаунт, входить у систему та переглядає запитувані дозволи. Застосунок, що належить акаунту, одразу відкриває акаунт-власник. Якщо політика безпеки вимагає схвалення адміністратора, Planfix відображає відповідний крок. Адміністратор може схвалити застосунок і підключити його однією дією.

Після успішної авторизації Planfix перенаправляє браузер на redirect_uri:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Код авторизації можна використати лише один раз, і він дійсний протягом 10 хвилин.

Отримання токенів

Надішліть POST-запит на /oauth/token, використовуючи application/x-www-form-urlencoded:

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

Для MCP повторно передайте параметр resource із тим самим значенням, що й у запиті авторизації.

Публічний клієнт надсилає запит без секрету. Конфіденційний клієнт також автентифікується за допомогою client_secret_basic або параметрів client_id і client_secret у тілі запиту.

Приклад відповіді:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Для REST API відповідь також містить account_name, account_domain і account_url. Збережіть ці значення та використовуйте URL-адресу вибраного акаунта для запитів REST API.

Токен доступу дійсний протягом 24 годин. Він прив’язаний до користувача, акаунта, застосунку, областей доступу та ресурсу. Токен, виданий для MCP, не можна безпосередньо використовувати з REST API, так само як токен REST API не можна використовувати з MCP.

Використання токена з REST API

Передайте токен у заголовку Authorization:

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Використовуйте URL-адресу акаунта, отриману під час обміну коду авторизації на токени. Доступні лише методи, на які поширюються надані області доступу. На токени OAuth поширюються обмеження тарифного плану акаунта та стандартні обмеження REST API.

Інформація про користувача

Для запиту userinfo потрібна область доступу openid:

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Приклад відповіді, якщо наявна область доступу email:

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Глобальна авторизація OAuth доступна співробітникам акаунта. Planfix не видає id_token; натомість запитуйте дані користувача через userinfo.

Оновлення токенів

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

Для MCP знову передайте той самий параметр resource. Конфіденційний клієнт має пройти автентифікацію за допомогою свого секрету.

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

Відкликання токена

Клієнт може відкликати токен оновлення через /oauth/revoke:

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Користувач також може видалити підключення в розділі Керування сеансами картки користувача. Адміністратор може відкликати схвалення стороннього застосунку для всього акаунта. Див. Додатки OAuth і MCP в акаунті.

Сумісність із наявними інтеграціями

Кінцеві точки для окремого акаунта, такі як https://account.planfix.com/api/v2/oauth/authorize, /token і /userinfo, продовжують працювати для наявних інтеграцій, прив’язаних до конкретного акаунта.

Для нових інтеграцій використовуйте глобальні кінцеві точки. Вони підтримують пошук стандартних метаданих, вибір акаунта та MCP. Не поєднуйте глобальні кінцеві точки й кінцеві точки для окремого акаунта в межах одного сеансу OAuth.

Рекомендації з безпеки

• Завжди використовуйте PKCE S256 і перевіряйте state.
• Для мобільних, настільних і браузерних застосунків використовуйте публічний клієнт без секрету.
• Використовуйте конфіденційний клієнт лише тоді, коли секрет можна надійно зберігати на сервері.
• Запитуйте мінімально необхідний набір областей доступу.
• Не записуйте в журнали токени доступу й оновлення, коди авторизації, code_verifier або секрети клієнта.
• Зберігайте токени оновлення та секрети клієнта в зашифрованому сховищі.
• Перевіряйте iss у відповіді та приймайте лише очікуваний емітент Planfix.

Можливі помилки

Помилка	Причина
invalid_client	Клієнта не знайдено або його вимкнено, секрет клієнта неправильний або застосунок недоступний у вибраному акаунті.
invalid_grant	Код авторизації або токен оновлення недійсний, прострочений, уже використаний або не відповідає клієнту, URI перенаправлення, даним PKCE чи ресурсу.
invalid_scope	Запит містить область доступу, не дозволену для застосунку.
invalid_target	Параметр resource не підтримується або його значення змінилося між запитами.
access_denied	Користувач відхилив підключення або політика акаунта не дозволяє використовувати застосунок.
HTTP 401, invalid_token	Токен доступу невідомий, прострочений або відкликаний.
HTTP 403, insufficient_scope	Токен не містить області доступу, необхідної для виконання операції.

Перейти

• MCP
• Додатки OAuth і MCP в акаунті
• OAuth-додатки для партнерів
• REST API
• REST API Authorization
• REST API: Access Levels List – scope