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 Metadata Document (CIMD) або Dynamic Client Registration (DCR).	Після реєстрації застосунок усе одно має бути допущений у вибраний акаунт.

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

Адреси OAuth

Нові інтеграції повинні використовувати глобальні endpoint. Ім'я акаунта в URL вказувати не потрібно: користувач вибирає акаунт під час авторизації.

Призначення	Адреса
Issuer	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

Redirect URI

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

Допускаються:

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

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

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

Застосунок отримує лише заздалегідь дозволені рівні доступу — scope. Повний перелік наведено в статті Список рівнів доступу REST API.

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

Для керованих застосунків також доступні службові scope userinfo, openid і email.

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

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

Приклад для 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	Один із дозволених Redirect URI.
response_type	Значення code.
scope	Потрібні застосунку права через пробіл. Для REST API параметр обов'язковий. MCP‑клієнт може не передавати його — тоді застосовується дозволений застосунку набір.
state	Випадкове значення для захисту від підміни запиту. Застосунок зобов'язаний перевірити його після повернення.
code_challenge	Base64url без padding від SHA-256 хешу code_verifier.
code_challenge_method	Лише S256.
resource	Для MCP — точний URL MCP‑сервера. Для REST API параметр не передається.

Для MCP використовується resource=https://mcp.planfix.com/mcp.

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

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

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

Authorization code одноразовий і дійсний 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. Збережіть їх і звертайтеся до REST API вибраного акаунта.

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

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

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

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

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

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

Для запиту userinfo потрібен scope openid:

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

Приклад відповіді за наявності scope 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 повертає новий access token і новий refresh token. Попередній refresh token одразу перестає працювати, тому застосунок має атомарно замінити збережене значення.

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

Клієнт може відкликати refresh token через /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 в акаунті.

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

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

Для нових інтеграцій використовуйте глобальні endpoint: вони підтримують стандартне виявлення конфігурації, вибір акаунта і MCP. Не змішуйте глобальні і tenant endpoint всередині одного OAuth‑сеансу.

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

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

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

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

Перейти

• MCP
• Додатки OAuth і MCP в акаунті
• OAuth-додатки для партнерів
• REST API
• Авторизація REST API по токену
• Список рівнів доступу REST API